éditeur on Framatophe Blog

Lettres et articles avec Zettlr ou Pandoc

situveuxmonadresse@demande-la.moi (Christophe Masutti) — Sun, 11 Apr 2021 00:00:00 +0000

Utiliser le célèbre convertisseur de document pandoc signifie manier (un tout petit peu) la ligne de commande. Rien de sorcier, pour peu d’être assez ouvert d’esprit pour comprendre qu’en matière de traitement de texte tout n’est pas censé se régler au clic de souris. Cela dit, le logiciel Zettlr permettent de s’affranchir de la ligne de commande tout en utilisant la puissance de pandoc. Zettlr propose une interface optimale pour écrire du texte en markdown et exporter dans différents formats. Il suffit d’aller voir dans les préférences avancées de Zettlr pour constater que ce dernier utilise une sorte de ligne de commande universelle avec pandoc pour réaliser ses exports. Pour ce qui concerne l’export en PDF, Zettlr utilise aussi LaTeX qu’il faudra installer sur la machine au préalable, tout comme pandoc.

J’ai écrit un petit billet sur Zettlr. Vous pouvez aller le lire pour mieux comprendre ce que je vais raconter ci-dessous.

Si vous n’avez pas envie de lire ce billet et souhaitez directement vous servir des modèles que je propose, vous trouverez l’ensemble sur ce dépôt GIT. Il y a un fichier README suffisant.

Pandoc et LaTeX

Qu’en est-il de la mise en page ? C’est là que les avantages combinés de pandoc et de LaTeX entrent en jeu : il est possible, en quelque sorte, de « programmer » la mise en page en élaborant des modèles qui utilisent différentes variables renseignées dans le fichier source en markdown. Bien entendu, on peut créer des modèles pour tout type d’export avec pandoc et d’ailleurs ce dernier utilise une batterie de modèles par défaut, mais ces derniers ne sont pas toujours adaptés à la sortie finale : qu’on utilise Zettlr ou non (ou n’importe quel éditeur de texte), il faut savoir compléter son fichier markdown avec des informations destinées à être taitées par pandoc.

Pour information, si pandoc s’utilise en ligne de commande, c’est parce qu’il y a toute une batterie d’options et de commandes que pandoc est capable d’exécuter. Pour éviter de les entrer systématiquement en ligne de commande, on peut les indiquer simplement dans l’en-tête du fichier markdown (ou dans un fichier séparé). Pour mieux comprendre de quoi il s’agit, vous pouvez vous reporter à ce document.

Pour donner un exemple trivial : si vous voulez que votre document markdown une fois exporté comporte un titre, un nom d’auteur et une date, il vous suffit de les indiquer de cette manière dans l’en-tête au début du document (on les appellera des « métadonnées ») :

``
% Le titre
% Prénom Nom
% 17/02/2021
``

Ou bien, en utilisant le format YAML :

``
---
title: "Le titre"
date: "17 février 2021"
author: "Prénom Nom"
...

``

Ainsi, pandoc les interprétera et, en utilisant un modèle par défaut ou un modèle de votre cru, reportera ces variables aux emplacements voulus dans la mise en page.

Si vous voulez écrire un article académique et le sortir en PDF en utilisant pandoc qui lui-même utilisera LaTeX, il vous faut donc réunir les éléments suivants :

un modèle LaTeX (ou se contenter des modèles LaTEX par défaut de pandoc),
des métadonnées à entrer après s’être bien renseigné sur la manuel d’utilisation de pandoc,
un fichier de bibliographie,
un fichier de style de présentation de la bibliographie.

En comptant les options courantes de pandoc que vous souhaitez utiliser, vous risquez de vous retrouver avec une ligne de commande assez longue… pour éviter cela, vous pouvez automatiser le tout avec un makefile que vous pourrez réutiliser plus tard pour d’autres documents, mais bigre… cela commence à devenir bien complexe pour qui n’a pas forcément envie d’y passer trop de temps, à moins de concevoir une fois pour toute une chaîne éditoriale que vous adapterez au fil du temps (c’est une option).

Zettlr et les modèles

Un grand avantage de Zettlr est de vous décharger de plusieurs de ces contraintes, en plus d’offrir une interface vraiment pratique entièrement destinée à l’écriture. Pour réaliser des exports, il vous faudra seulement installer pandoc. Et pour réaliser des exports PDF, il vous faudra installer LaTeX (je préconise une installation complète, par exemple Texlive-full).

Le fichier et le style CSL de bibliographie ? il vous suffit de les renseigner dans les préférences de Zettlr une fois pour toutes.

Le modèle de sortie PDF ? idem, vous le renseignez dans les préférences d’export PDF.

Et pour exporter ? il vous suffira de cliquer sur l’icône PDF.

Tout cela demeure assez simple, sauf que si vous rédigez un article sans chercher à travailler la question des métadonnées, votre sortie PDF risque de vous décevoir : pandoc utilisera le modèle par défaut, c’est-à-dire la classe [article]de LaTeX, qui en soi est une excellente mise en page, mais ne colle pas forcément à vos souhaits.

Réaliser des modèles pour pandoc est chose assez facile. En effet, si vous comprenez des notions informatiques basiques comme « pour…si…ou…alors », la syntaxe des modèles pandoc ne posera guère de problème. Il faudra néanmoins maîtriser LaTeX si vous voulez créer un modèle LaTeX.

Mes modèles article, rapport et lettre

Pour vous éviter d’y passer trop de temps, je vous propose d’utiliser mes modèles élaboré pour des articles, des rapports ou des lettres simples.

J’ai pris le parti de réaliser un modèle LaTeX destiné à chaque fois à la sortie voulue, là où le modèle pandoc par défaut permet de créer un article, une présentation ou un livre en indiquant simplement la classe voulue. Ce modèle par défaut inclu donc de nombreuses variables mais à trop vouloir être généraliste, je pense qu’on loupe l’essentiel.

Pour utiliser mes modèles, il vous suffit de réutiliser les fichiers markdown renseigner les différents éléments présents dans les en-têtes YAML de ces fichiers. Si vous voulez modifier les modèles eux-mêmes, il vous suffit de les éditer : j’ai tâché de commenter et de bien séparer les éléments importants.

Ces modèles utilisent KOMA-script, la classe scrartcl pour les article, scrreprt pour les rapports et scrlttr2 pour les lettres. Si vous connaissez LaTeX, vous comprendrez que KOMA-script est un excellent choix pour des documents européens (il fut créé au départ pour des documents de langue allemande, mais il fut rapidement adapté à différentes pratiques d’écriture, dont le Français).

Pour résumer très simplement :

si vous écrivez une lettre, renseignez dans Zettlr le chemin vers le modèle dans les préférences d’export PDF,
si vous écrivez un article ou un rapport, renseignez dans Zettlr le chemin vers le modèle dans les préférences d’export PDF et notez que le modèle utilise les styles CSL pour la bibliographie (pas de biblatex ou de natbib, donc),
si vous ne voulez pas utiliser Zettlr, et uniquement pandoc, je vous ai indiqué dans le README les lignes de commande à utiliser (ce sont celles qu’utilise Zettlr, en fait).

Vous trouverez l’ensemble sur ce dépôt GIT.

Affaires privées : les coulisses

situveuxmonadresse@demande-la.moi (Christophe Masutti) — Tue, 02 Jun 2020 00:00:00 +0000

À la suite d’un échange sur une plateforme de microblogage, j’ai promis de décrire ma méthode de production de manu-(tapu)scrit en vue de l’édition d’un livre. Ce billet vise à montrer à quel point les formats ouverts sont importants dans un processus d’écriture. Il témoigne de mes préférences et n’est en aucun cas une méthode universelle. Cependant j’ose espérer qu’il puisse donner quelques pistes profitables à tous !

Identification des besoins

Le livre dont il est question ici (il est bien, achetez-le !) s’intitule Affaires privées. Aux sources du capitalisme de surveillance, publié chez C&F Éditions, mars 2020. Il fait un peu moins de 500 pages. La production du manuscrit proprement dit (le fichier qu’on envoie à l’éditeur) m’a pris environ 5 mois. Sur cette base, l’équipe éditoriale (qu’elle en soit ici remerciée) s’est livrée au travail de relecture, avec plusieurs va-et-vient avec moi pour les corrections, et enfin un gros travail de mise en page.

Ce dont je vais traiter ici concerne la production du tapuscrit, et donc le processus d’écriture proprement dit, qui regarde essentiellement l’auteur. Pour le reste, il s’agit d’un travail éditorial avec d’autres contraintes.

Au risque d’être un peu caricatural il va me falloir décrire rapidement ce qu’est un travail de recherche en histoire et philosophie des sciences. On comprendra mieux ainsi pourquoi le choix des formats de fichiers est important dans l’élaboration d’un flux de production d’écriture pour un document long, comme un livre, ou même lorsqu’on s’apprête à écrire un article.

Dans ce type de travail, il ne suffit pas de récolter des documents historiques (pour ce qui me concerne, il s’agit de textes, photos, vidéos). Ces sources sont stockées dans différents formats, surtout des PDF (par exemple des fac-similés, des copies d’articles), des transcriptions sous forme de texte (le plus souvent dans un format texte de base), etc. Étant donnée cette diversité, un premier impératif consiste à ne pas sur-ajouter des formats et tâcher de faire en sorte que les notes de consultation soient accessibles dans un format unique et le plus malléable possible. Par ailleurs, se pose aussi la question du stockage de ces sources : les avoir à disposition, où que je me trouve, et m’assurer de la pérennité de leur sauvegarde.

Outre les sources, je dispose de travaux d’écriture préalables. Écrire un manuscrit en 5 mois n’est possible qu’à la condition d’avoir aussi à disposition une matière déjà travaillée en amont, comme un terrain préparatoire à l’écriture proprement dite. Il faut considérer ces travaux préparatoires comme des sources avec un statut particulier.

Il en est de même pour les notes de lectures qui sont aussi des réflexions sur les enjeux philosophiques, historiques et politiques, la méthodologie, les idées critiques, bref des sources particulières puisque produites par moi et toujours soumises à modifications au fur et à mesure de la maturité d’une pensée et de l’acquisition de connaissances.

Se pose ensuite la question du recensement des sources et, de manière générale, toute la bibliographie qu’il faudra utiliser dans le manuscrit. Dans ce genre de discipline, au risque de barber sérieusement le lecteur, une forme d’obligation consiste à citer la bibliographie « à la page » chaque fois que cela est possible. Afin de pouvoir mobiliser ces éléments qui se chiffrent par centaines, il faut bien entendu avoir un système capable de trier, classer, et sortir des références bibliographiques exploitables.

Un autre impératif consiste à élaborer un flux d’écriture qui soit à la fois rapide et efficace tout en l’édulcorant au maximum des contraintes logicielles. Ces contraintes peuvent être liées à la « lourdeur » du logiciel en question, par exemple le temps passé à saisir la souris pour cliquer sur des icônes est autant de temps en moins consacré à l’écriture. Se libérer de ces contraintes va de pair avec une certaine libération des contraintes matérielles : l’idéal consiste à pouvoir écrire sur différents supports c’est-à-dire un ou plusieurs ordinateurs, un smartphone ou une tablette. Pour ce qui me concerne, se trouver coincé par l’accès à un logiciel sur un seul type de support m’est proprement insupportable.

En résumé, les besoins peuvent s’énumérer ainsi : écrire, utiliser différentes machines, synchroniser et sauvegarder, gérer et exploiter une bibliographie, produire un résultat. Allons-y.

Écrire

C’est de plus en plus répandu : les utilisateurs qui produisent du contenu en écriture n’utilisent plus uniquement les logiciels de traitement de texte tels MSWord ou LibreOffice Writer en première intention. Demandez-vous par exemple ce qu’utilisent tous les blogueurs via des interfaces d’écriture en ligne, ou regardez de près le logiciel de prise de notes que vous avez sur votre smartphone : la mise en page est assurée ultérieurement, tout ce que vous avez à faire est simplement d’écrire.

Si j’ai traduit et adapté un manuel sur LibreOffice Writer, c’est parce que je considère ce logiciel comme l’un des plus aboutis en traitement de texte mais aussi parce que le format Open Document est un format ouvert qui permet l’interopérabilité autant qu’un travail post-production. Il en est de même pour LaTeX (qui est un système de composition) et dont les fonctionnalités sont quasi infinies. J’adore LaTeX.

Alors… pourquoi ne pas utiliser d’emblée l’un de ces deux logiciels ? Parce que ce dont j’aimerais vous parler ici, ce n’est pas de la production de document, mais de l’écriture elle-même. Mélanger les deux signifie anticiper la production finale (au risque de se tromper). Quoi qu’on en dise, c’est en tout cas mon cas, on se laisse facilement distraire par les fonctionnalités du logiciel.

Pour écrire, et simplement écrire, je n’ai besoin que d’un éditeur de texte. C’est-à-dire un logiciel qui me permet d’entrer du texte et d’enregistrer sans information de formatage (on parle de plain text) ou alors le strict minimum. C’est sur ce strict minimum qu’il faut réfléchir en allant un peu plus loin dans le raisonnement.

En effet, lors de la production finale, je n’ai pas très envie de revenir sur chaque partie du texte nécessitant un traitement typographique au cours de l’écriture. Par exemple certains mots en emphase, le signalement des titres de parties, sections et sous-sections. Idem, j’ai aussi besoin de pouvoir formater mon texte de manière à ce qu’il se prête ultérieurement à toutes les transformations envisageables nécessitant un processus de traitement comme la génération des références bibliographiques ou l’ajout de liens (URLs). Ces choses-là sont toujours possibles en plain text mais il y a des solutions plus pratiques.

Il existe un format très intéressant : le markdown. C’est du texte, mais avec quelques ajouts d’informations très simples qui permettent un traitement ultérieur lors de la production finale. Ce langage de balisage est léger. Il nécessite un apprentissage de quelques minutes et il s’applique facilement au cours de l’écriture sans la freiner outre mesure. C’est dans ce format que j’écris, y compris par exemple le texte de ce billet de blog. Ce format est par définition ouvert (cela reste du texte).

En pratique, il ne reste plus qu’à choisir l’éditeur de texte ou un éditeur de texte spécialisé en markdown. Sur ce point j’ai déjà eu l’occasion de me prononcer sur ce blog. Par aillieurs, j’accorde beaucoup d’importance au confort visuel de l’écriture. La possibilité de configurer l’affichage l’éditeur (couleurs du fond, style de la police, de la syntaxe, raccourcis, etc.), en jouant notamment sur les contrastes, me permet d’écrire plusieurs heures durant sans avoir trop de gêne visuelle. Il s’agit d’un confort personnel. Il y a d’autres fonctionnalités que l’on trouve dans les éditeurs de texte¹, par exemple :

éditer le texte à plusieurs endroits à la fois avec un split de fenêtres,
faire des recherches sur des expressions régulières,
un panneau latéral ouvrant le contenu du dossier sur lequel on travaille,
le surlignage d’occurrences,
la possibilité d’avoir accès à un terminal sans quitter l’éditeur²,
etc.

Enfin, j’y reviendrai plus tard, l’utilisation de fichiers non binaires se prête admirablement à l’utilisation de Git, un outil de gestion de version qui, dans mon cas, me sert surtout à sauvegarder et synchroniser mon travail d’écriture. Et il se prête tout aussi admirablement à la conversion vers d’autres formats à leur tour exploitables tels odt, html et tex.

Mes éditeurs de texte préférés du moment sont les suivants : Gedit, Atom, Ghostwriter. Depuis peu, j’utilise aussi Zettlr pour mes notes, voyez ici.

Utiliser différentes machines

Au fur et à mesure de l’avancée des travaux, on se retrouve généralement à utiliser différents dispositifs. La question se pose : doit-on réserver uniquement la tâche d’écriture à l’ordinateur de son bureau ? Pour moi, la réponse est non.

Sur tous les ordiphones et tablettes, il existe des logiciels de prise de notes qui utilisent le format texte et, comme c’est souvent le cas, le markdown. L’application Nextcloud, par exemple, permet aussi d’utiliser Nextcloud Notes, un logiciel de prise de notes qui synchronise automatiquement les notes sur un serveur Nextcloud (on peut le faire aussi avec n’importe quelle application de notes pourvu que l’on sauvegarde ses fichiers dans le dossier synchronisé). Cela est utile dans les cas suivants :

le processus d’écriture n’est pas toujours « sur commande ». Même si les meilleures idées ne surgissent pas toujours inopinément, et même si bien souvent ce qu’on pensait être une bonne idée s’avère être un désastre le lendemain, il est utile de pouvoir développer quelques passages sans pour autant être assis à son bureau. J’utilise pour cela Nextcloud Notes, soit en tapant directement la note, soit par dictée vocale.
recopier tout un texte lorsqu’on est en train de consulter des documents ? que nenni, soit on utilise un scanner et un logiciel de reconnaissance de caractères, soit on peut carrément utiliser son ordiphone (avec ce logiciel par exemple), pour produire un texte à placer dans ses notes.

L’essentiel est de ne pas dépendre d’un dispositif unique présent dans un lieu unique. On peut utiliser plusieurs ordinateurs et des lieux différents, utiliser l’ordiphone qu’on a toujours avec soi, la tablette sur laquelle on lit un livre et exporte des notes de lecture…

Tout ceci permet de générer rapidement des ressources exploitables et de les organiser en provenance de différents outils. Pour cela d’autres logiciels doivent encore être utilisés afin de sauvegarder et de synchroniser.

Synchroniser et sauvegarder

Comme je viens d’en discuter, l’organisation est primordiale mais s’en préoccuper sans cesse est plutôt lassant. Mieux vaut automatiser le plus possible.

Séparons dans un premier temps ce qui a trait à la gestion des sources documentaires et la production écrite.

Pour la gestion documentaire, l’ensemble est stocké sur un serveur Nextcloud (hébergé sur un serveur de confiance³). Sur chaque machine utilisée, une synchronisation est paramétrée avec un client Nextcloud. On travaille directement dans le dossier qui se synchronise automatiquement.

Pour la production écrite, c’est Git qui sera utilisé avec un serveur Gitlab (Framagit en l’occurrence). Sont concernés les fichiers suivants :

l’écriture des chapitres (fichiers .md),
les notes (autres que les notes de lecture) (fichiers .md),
le fichier bibtex de la bibliographie (contenant aussi le référencement descriptif de chaque source documentaire ainsi que les notes de lecture) (fichiers .bib).

Pour terminer, il faut aussi penser à faire une sauvegarde régulière de l’ensemble sur le second disque dur de la machine principale sur laquelle je travaille, doublée d’une sauvegarde sur un disque externe. La première sauvegarde est automatisée avec rsync et tâche cron exactement comme c’est décrit dans ce billet. La seconde tâche pourrait aussi être automatisée, mais je la fais manuellement pour éviter de toujours laisser branché le disque externe.

Gérer la bibliographie

Gérer sa bibliographie ne s’improvise pas. Il faut d’abord trouver le logiciel qui répond à ses attentes. Le choix est assez large pourvu que le logiciel en question puisse être en mesure d’exporter une bibliographie dans un format ouvert, exploitable par n’importe quel autre logiciel.

En la matière, selon moi, les deux formats intéressants sont le .bib et le .xml. Au stade de l’écriture, l’essentiel est donc de choisir un logiciel avec lequel on se sent à l’aise et dont les fonctionnalités d’export sont les plus étendues possibles. J’ai choisi Zotero et JabRef.

Pourquoi ces deux logiciels ? Dans les deux cas, des extensions permettent de les intégrer au navigateur Firefox (ainsi qu’à LibreOffice). Dans les deux cas on peut synchroniser la biblio en ouvrant un compte Zotero ou en plaçant son fichier .bib sur Nextcloud dans le cas de JabRef.

Mon usage est un peu exotique, je l’avoue : j’utilise Zotero pour engranger un peu tout et n’importe quoi et j’utilise JaBref pour mon travail proprement dit en utilisant le format .bibet souvent en éditant directement le fichier avec un éditeur de texte. Disons que le .bib final est un fichier très « propre » contenant pour l’essentiel la bibliographie citée alors que Zotero contient un peu de tout au gré des récupérations avec l’extension Firefox. Ce n’est pas l’essentiel : quoi qu’il en soit, lors de la production finale, on configurera ce qui doit apparaître ou non dans la bibliographie.

Enfin, je préfère utiliser le .bib car il est fait au départ pour le logiciel Bibtex lui-même destiné à une utilisation avec LaTeX. Si je veux pouvoir avoir le choix de production finale, autant utiliser ce format. En outre, sa lisibilité lorsqu’on l’édite avec un éditeur de texte permet de retravailler les informations, surtout en cas de problème d’encodage.

Produire un résultat

Nous voici arrivés à la production du manuscrit (on dit plutôt un tapuscrit dans ce cas). Il faut alors se demander ce que veut l’éditeur. Dans notre cas, il s’agissait de produire un fichier .odt avec une présentation complète de la bibliographie.

Nous avons à disposition des fichiers markdown et un fichier bibtex. On peut en faire exactement ce qu’on veut, à commencer par les éditer ad vitam æternam en plain text.

On notera que pour entrer des références bibliographique dans un document en markdown, la syntaxe est très simple et l’utilisation est décrite dans plusieurs billets de ce blog.

On utilisera pour cela un logiciel libre du nom de Pandoc qui permet non seulement de convertir du markdown en plusieurs types de formats mais aussi d’effectuer simultanément des opérations de compilation pour la bibliographie avec un processeur CSL nommé citeproc.

En effet, pour présenter la bibliographique il faut utiliser un format de style bibliographique. On utilise le Citation Style Language (CSL) qui est basé sur un agencement de champs en XML. Pour créer un modèle CSL, le mieux est encore de partir sur la base de modèles existants et adapter le sien. Il existe par exemple cet éditeur CSL.

En d’autres termes il s’agit d’ordonner ceci à Pandoc :

S’il te plaît, transforme mon fichier markdown en fichier au format .odt tout en utilisant la bibliographie que voici au format .bib et le modèle de présentation de bibliographie .csl que voici.

La ligne de commande est alors la suivante :

pandoc -s --bibliography mabiblio.bib --filter pandoc-citeproc --csl modif-monmodele.csl fichier-entree.md -o fichier-sortie.odt

Cela c’est pour l’éditeur ! pour ce qui me concerne, ce sera plutôt une transformation en .tex et une bonne vieille compilation avec XeLaTex + Biber avec un style de mise en page sympathique. De même… pour du epub.

Le seul ennui est qu’à ce stade il fallait encore travailler le texte et tout le processus de relecture qui s’est déroulé exclusivement avec LibreOffice Writer et la fonction de suivi de modification. On a donc quitté la quiétude des fichiers texte pour entrer dans un processus d’échange de fichiers .odt. Ce travail aurait tout aussi bien pu s’effectuer avec Git, évidemment. Mais au bout du compte il aurait tout de même fallu créer un .odt avec les styles de l’éditeur afin d’entrer le tout dans la moulinette de son processus éditorial. Mais cela ne nous… regarde pas.

Conclusion

Comme on peut le voir, tout le processus considère le fichier .odt comme un format obtenu en fin de production et non pas un format sur lequel on travaille directement. C’est une posture qui se justifie par la volonté de conserver la plus grande malléabilité possible sur les résultats finaux et sur la manipulation des fichiers de travail.

Par ailleurs concernant le flux de production d’écriture, une fois l’habitude prise, il est extrêmement confortable d’écrire « au kilomètre » dans un éditeur de texte bien configuré et qui, par sa légèreté n’a besoin que de très peu de ressources système.

Toute l’importance des formats ouverts est là, tant au niveau de la lecture avec différents logiciels qu’au niveau de la production finale et l’interopérabilité qu’ils permettent. De la même manière, on peut voir que tout le travail s’est effectué avec des logiciels libres (et sur des systèmes d’exploitation libres). Le grand choix dans ce domaine permet à chacun de travailler selon ses envies et ses petites manies.

Certaines de ces fonctionnalités se retrouvent aussi sur LibreOffice Writer, bien entendu, mais je trouve que leur accès est plus rapide dans un éditeur de texte simple. ↩︎
Certains me diront d’utiliser Emacs ou Vim. C’est ce que je fais de temps en temps mais l’apport vis-à-vis de mon travail n’est pas significatif. ↩︎
Il s’agit de mon serveur à moi et aussi du serveur destiné à l’usage interne des membres de l’association Framasoft. J’utilise les deux mais c’est un détail. ↩︎

Zettlr : markdown puissance dix

situveuxmonadresse@demande-la.moi (Christophe Masutti) — Tue, 18 Feb 2020 00:00:00 +0000

Le logiciel libre a toujours quelque chose de magique. Cédant au plaisir coupable d’une attitude consommatrice, on se met à essayer frénétiquement plusieurs solutions logicielles, rien que « pour voir ». Zettlr fera-t-il partie de ces nombreux éditeurs markdown que je recense dans l’espoir de trouver le Graal du genre ? Attention : on n’essaye pas Zettlr sans en comprendre d’abord les objectifs.

Comparaison et flux de travail

Dès les premières pages de présentation dans la documentation de Zettlr, on voit clairement que pour se servir de ce logiciel, il faut de bonnes raisons.

On peut expliquer ces raisons en comparant Zettlr avec d’autres éditeurs spécialisés dans le markdown. Essayons par exemple de le comparer Ghostwriter (j’en ai parlé dans ce billet), du point de vue utilisateur.

La première différence c’est que là où Ghostwriter propose une interface très facile et rapide à prendre en main… Zettlr n’est pas aussi explicite. Bien sûr, on peut d’emblée commencer à écrire en markdown, enregistrer un fichier, mais ce n’est pas le but unique de Zettlr. Si Ghostwriter se concentre avant tout sur la partie éditeur, Zettlr est à la fois dédié à l’écriture et à la gestion de connaissances. Et pour cause, il a été créé et il est utilisé essentiellement dans le monde universitaire. C’est donc dans un contexte qui concerne les documents longs qu’il faut appréhender Zettlr, là où Ghostwriter servira bien la cause pour écrire un billet de blog, par exemple.

En fait tout se joue dans la manière dont on intègre un éditeur markdown dans un flux de travail. Dans mon cas, l’éditeur que j’utilise ne constitue pas un nœud décisif, ce qui fait que, selon les situations, je peux opter pour un autre éditeur (spécialisé ou non dans le markdown) pour continuer à travailler sur le même document.

J’aime bien avoir cette possibilité d’utiliser plusieurs éditeurs pour un même fichier, indépendamment du système sur lequel je travaille. Ensuite, pour produire le document final, j’exporte directement dans un format donné (si l’éditeur le permet) ou bien j’utilise pandoc qui me permet de transformer le fichier markdown en à peu près tout ce que je veux. Dans ce cas, je « sors » de l’éditeur pour utiliser la ligne de commande, puis une fois le document produit, j’utilise un autre logiciel pour terminer ma production selon le format choisi (LibreOffice pour.odt, un éditeur TeX pour(La).TeX, un éditeur de texte pour le .html, LibreOffice pour .docx, etc.). Pour les questions liées à la gestion de la bibliographie, c’est un peu complexe, puisque je suis contraint d’ouvrir, en plus de mon éditeur, un gestionnaire de bibliographie tel Zotero ou JabRef, repérer les clé bibtex des références, les insérer sous la forme [@dupont1955].

Tout dépend des goûts, mais on voit bien qu’un éditeur markdown trouve vite ses limites lorsqu’on commence à intégrer le markdown dans une démarche de rédaction plus « soutenue » et afin de rédiger des documents longs. Des allers-retour avec d’autres logiciels (notamment pour la gestion de la bibliographie) sont nécessaires.

Bien sûr les éditeurs comme Ghostwriter permettent de faire des exports en différents formats. Ils peuvent même créer du PDF en utilisant LaTeX (c’est d’ailleurs l’option recommandée pour un bon résultat, à condition d’avoir préalablement installé LaTeX). Mais il faut savoir se méfier des solutions qui prétendent tout faire. Ainsi, lorsqu’on commence à manipuler de la bibliographie, les « exports-gadgets » sont plus encombrants qu’autre chose. Cependant, il faut reconnaître que Zettlr a plutôt bien réussi à intégrer ces fonctionnalités d’export.

Pour ce qui me concerne, la solution que j’ai adoptée consiste à utiliser un éditeur de texte nommé Atom qui dispose d’extensions permettant d’écrire en markdown, faire de l’autocomplétion avec du Bibtex, intégrer un convertisseur avec pandoc et utiliser la console pour lancer des commandes (et plein d’autres choses). Cela me permet d’avoir mon flux de travail concentré pour l’essentiel sur un seul logiciel et utiliser les fonctionnalités au besoin, en gardant l’avantage de segmenter l’activité.

Alors, si de tels couteaux suisses existent, me demanderez-vous, pourquoi s’intéresser à Zettlr ? parce que les couteaux suisses demandent un temps d’apprentissage assez long, disposent d’une foule de fonctionnalités au point de s’y perdre et que Zettlr cherche à concentrer l’essentiel (avec quelques bémols toutefois).

De la gestion de connaissance

Avant de parler des fonctionnalités concrètes de Zettlr, il faut questionner l’ambition générale de ce logiciel.

Il a été créé essentiellement pour les chercheurs et les écrivains. C’est d’ailleurs un chercheur en sciences humaines, Hendrik Erz, qui a créé Zettlr afin de pouvoir sortir du carcan « traitement de texte » qui ne correspond pas vraiment aux besoins lorsqu’on écrit ou prend des notes dans une activité de production de connaissances (là où le traitement de texte devrait intervenir à une étape ultérieure de « mise au propre »).

Quels sont ces besoins ? pouvoir écrire en se concentrant sur ce qu’on écrit, tout en disposant d’une aide pour accéder aux ressources cognitives qu’on aura prit soin d’organiser en amont.

Cette organisation passe par la gestion bibliographique (à l’aide de logiciels dédiés tels Zotero) ainsi que par la gestion des notes et autres notices ou fiches que l’on stocke dans un système de pensée qui nous est propre.

Pour ce qui concerne la gestion bibliographique, l’utilisation de logiciels dédiés (et capables de sortir différents formats de bibliographie) est une habitude que bon nombre de chercheurs ont déjà (si ce n’est pas le cas, il y a un problème). Zettlr permet d’intégrer l’utilisation de références bibliographiques au cours du travail d’écriture dans l’éditeur markdown. Il suffit de renseigner le fichier .bib (ou CSL Json, qu’on obtient avec Zotero) puis Zettlr permet son utilisation au cour de la frappe. Cela rappelle par exemple l'extension Zotero qu’on installe dans LibreOffice, mais de manière plus brute et beaucoup plus fluide.

Pour ce qui concerne la mobilisation des connaissances, Zettlr a été conçu pour créer un système de Zettelkästen. On le note en allemand (ici au pluriel) parce que, pour un néophyte qui se rendrait dans les options de configuration de Zettlr, il y a une rubrique entièrement dédiée au « flux de travail Zettelkasten », et très franchement ça peut surprendre (sauf qu’on comprend aussi pourquoi Zettlr se nomme ainsi).

Une Zettelkasten signifie littéralement « boîte » (der Kasten) à notices ou pense-bêtes (der Zettel). Personnellement j’appelle cela une « boîte à fiches ». Dans ce cas, direz-vous, il y a déjà des logiciels spécialisés dans les « notes », y compris en permettant de synchroniser en ligne, avec une interface pour smartphone, etc. Oui, évidemment, et il n’est pas idiot de penser que, dans la mesure où ces logiciels de prise de notes utilisent le plus souvent le markdown, ces notes peuvent aussi être ouvertes avec Zettlr (c’est que je fais). Mais cela va plus loin.

Zettlr permet de créer des fiches tout en créant soi-même un système de rangement. C’est ce qui est expliqué ici. Le logiciel ne cherche pas à formater les notes ou à créer une seule manière de les rédiger ou les stocker : c’est à vous de créer votre système de rangement. On utilise alors pour cela les outils courants de liens externes entre les fiches et les mots-clés qu’on note pour chaque fiche. Un genre wiki, si on veut (même si un logiciel comme Dokuwiki sera bien plus puissant), mais sans quitter Zettlr.

L’intérêt réside selon moi dans la création et le nommage des fiches. Selon le besoin, il est possible de configurer l’identifiant de la fiche (le nom du fichier) et créer des liens entre les fiches en profitant de l’assistant (menu contextuel qui liste les noms de fiche). Ces fonctionnalités sont très simples, on pourra même les qualifier de basiques, mais à l’utilisation quotidienne, elle permettent un réel gain de temps… Et à propos de temps on notera que si Zettlr propose un format d’export en Org (pour Emacs), ce n’est pas pour rien !

Aide à la saisie

Zettlr est d’abord un éditeur markdown et le moins qu’on puisse dire est qu’il accompli ce rôle avec brio. L’aide à la saisie, indissociable de l’interface, est soignée.

Outre un petit menu, en haut, dédié à la mise en forme, on notera :

la visibilité automatique des titres de section, avec la possibilité de masquer la section ;
l’aide à la saisie de tableaux ;
quelques raccourcis et astuces (voir la documentation) tels la combinaison Ctrl + alt + F qui permet d’entrer une référence de note de bas de page automatiquement, ou encore Ctrl + alt + pointage curseur qui permet de saisir le même texte à deux endroits en même temps…

Correction en cours de frappe

L’ajout d’une fonction de correction basée sur des dictionnaires est quelque chose d’assez banal. Zettlr l’intègre pour plusieurs langues et c’est un atout très important. Mais pour un éditeur markdown, la possibilité de configurer soi-même la correction en cours de frappe est, osons le dire, assez exceptionnel. Ainsi, dans Paramètres > AutoCorrect il est possible d’activer l’utilisation des guillemets selon le contexte linguistique, mais aussi toutes sortes de saisies utiles, en particulier pour la typographie. Ainsi, on peut faire en sorte que la frappe d’un double point soit remplacée par une séquence qui associe une espace insécable (AltGr + Esp) et un double point, et toutes autres joyeusetés relatives aux règles typographiques.

Travailler par projet

Comme le font beaucoup d’éditeurs, en particulier pour la programmation, l’utilisation de Zettlr sera d’autant plus efficace si vous optimisez la gestion des fichiers en créant un dossier par projet. C’est ce dossier que vous ouvrez alors, et c’est dans ce dossier que seront listés les fichiers que vous créez (dans le panneau de gauche). Ainsi, dans les options d’export, je conseillerais plutôt de cocher l’option qui consiste à sauvegarder les fichiers exportés dans le dossier en cours.

La bibliographie

Comme mentionné plus haut, Zettlr fournir un outil d’aide à la saisie de références bibliographiques.

Le principe qui a été retenu par les créateurs est celui-ci : dans les paramètres, vous entrez le chemin du fichier de bibliographie que vous avez créé. Vous pouvez entrer un fichier .bib ou un fichier .json créé par exemple avec Zotero.

À la différence de la gestion bibliographique via une extension Zotero ou JabRef dans le logiciel de traitement de texte tel LibreOffice, il faut entrer le chemin du fichier .bib ou .json dans les paramètres et ce seront ces données qui seront utilisées par Zettlr. Évidemment, si vous complétez votre bibliographie il faut s’assurer que Zettlr pourra bien trouver dans le fichier vos nouvelles références sans pour autant remplacer le fichier à chaque fois et devoir recharger Zettlr. Une fonctionnalité de Zotero vous sera très utile pour cela :

Dans Zotero, sélectionnez la bibliothèque que vous souhaitez exporter, clic droit puis Exporter la bibliothèque
Sélectionnez le format Better BibTeX ou Json et cochez la case Garder à jour
Sauvegardez et entrez le chemin vers ce fichier dans Zettlr
Désormais, lorsque la bibliothèque Zotero subira des modifications, le fichier d’export sera toujours à jour (et vous retrouverez vos nouvelles références)

À mes yeux, c’est une posture bancale. Certes, le fichier sera toujours à jour mais c’est une fonctionnalité qui dépend d’un autre programme (et tant pis si vous n’aimez pas Zotero). Par ailleurs, cela implique aussi que le fichier de bibliographie soit le même pour tous vos projets, ce qui signifie que si, comme moi, vous avez une biblio séparée pour chaque projet dans Zotero, la seule bibliothèque à exporter, c’est la principale. Cela dit, une fois configurée la bibliographie, Zettlr permet l’autocomplétion des références, ce qui est déjà d’une grande aide.

Ceci est valable aussi pour la configuration du format de bibliographie à la production de sortie, c’est-à-dire à l’export. En effet, pour formater la bibliographie, Zettlr permet de sélectionner le fichier de style CSL (que vous pourrez trouver sur ce dépôt ou via ce configurateur – reportez-vous à la section Bibliographie de ce billet pour comprendre de quoi il s’agit). Là encore, l’idée me semble bancale : si vous rédigez plusieurs documents avec des exigences différentes de format de bibliographie, il faut changer à chaque fois.

Donc idéalement, l’une des prochaines améliorations de Zettlr devrait inclure une solution d’extension Zotero ou JabRef capable de générer le fichier de bibliographie final à la volée et une solution de sélection de fichiers de style CSL. Plus facile à dire qu’à faire…

Export et pandoc

Pour utiliser les fonctionnalités d’export de Zettlr, il vous faut le logiciel pandoc installé sur votre système. Vous ne serez pas efficace si vous ne connaissez pas dans les grandes lignes le fonctionnement de ce logiciel… Qui ne connaît pas pandoc aura toutes les peines du monde à comprendre comment Zettlr exporte les fichiers dans un format choisi.

Pandoc est un logiciel de conversion muti-format très puissant et avec des résultats très propres (il ne s’encombre pas de formules polluantes qui rendent inutilisables les fichiers produits). Là où pandoc prend toute sa valeur dans notre cas, c’est qu’il permet de transformer le format markdown en à peu près tout ce que vous voulez. Par ailleurs, il est capable non seulement de convertir, mais aussi de convertir en utilisant des modèles et même d’autres logiciels qui paramètrent la conversion. Je vous invite à lire ce billet à propos de la manipulation de documents markdown et ce billet à propos de pandoc et LaTeX pour vous faire une idée (complétez aussi par celui-ci).

Ces lectures vont vous permettre de mieux comprendre la section des paramètres avancés de Zettlr.

Dans l’illustration, la liste des annexes concerne les fichiers que vous allez voir figurer dans le panneau latéral de droite (en cliquant sur la petit trombone) lorsque vous liez des documents annexes à votre document. Quant aux chemins vers pandoc et XeLaTeX, inutile de vous en soucier, pourvu que ces programmes soient bien installés.

Ce qui nous intéresse dans les paramètres avancés, c’est la commande pandoc réservée aux « utilisateurs avancés seulement ». Parce qu’en réalité, elle détermine comment pandoc doit fonctionner avec Zettlr. Essayons de comprendre.

Pandoc est un logiciel dont l’usage est simple. Ce n’est pas parce qu’il s’utilise en ligne de commande que cela en fait un logiciel compliqué. La preuve : pour utiliser pandoc, vous devez lancer la commande pandoc en précisant le fichier sur lequel vous voulez travailler, le nom du fichier à produire et les options et formats choisis pour la conversion. Ainsi la commande

$pandoc source.md -o sortie.odt

Consiste à produire un fichier .odt nommé « sortie » à partir d’un fichier nommé « source ». Le -o signifie « output » (vers la sortie).

Une variante pourrait être : $pandoc -f markdown -t odt bonjour.md … c’est à dire transformer le fichier « bonjour.md » du markdown vers (-f c-à-d. : from markdown vers -t c-à-d. : to) le .odt.

Ça va jusque là ? vous voyez il n’y a rien de compliqué. Continuons un peu.

Pandoc ne fait pas « que » convertir. Il est capable de convertir en utilisant des informations beaucoup plus complexes et qui permettent même d’enrichir le fichier de départ, surtout si ce dernier n’est qu’en markdown. Par exemple :

avec le programme citeproc il est capable d’interpréter un format de bibliographie (en CSL) et on aura pris soin de renseigner dans la ligne de commande à la fois l’option citeproc et le chemin vers le fichier de bibliographie ;
avec reveal.js il est capable de sortir, à partir d’un fichier markdown rédigé à cette intention, une très jolie présentation en HTML qu’il reste à afficher dans un navigateur en vue de faire une conférence.

Maintenant imaginez que vous n’avez pas le nom du fichier source ni le nom de sortie et que vouliez permettre à un utilisateur de choisir le format de sortie. Et bien il vous reste à créer une ligne de commande qui, au lieu de donner des instruction rigides, propose des valeurs (avec des $ qui seront utilisées (ou pas). Et vous voilà avec la ligne de commande que propose Zettlr dans les paramètres avancés.

Exporter en PDF

L’export au format PDF à partir de Zettlr suppose que vous ayez LaTeX (et XeLaTeX) installé sur votre système. Si tel est le ca,s il vous reste à vous rendre dans le menu fichier > Paramètres de PDF afin d’y renseigner divers éléments dont un modèle .tex qui pourra être utilisé. Rendez-vous sur la documentation de Pandoc pour apprendre à vous en servir.

Attention : Si vous avez une version de pandoc antérieure à 2.0 (c’est le cas pour beaucoup d’installations), Zettlr (via pandoc) retournera une erreur du type unrecognized option --pdf-engine=xelatex. L’explication se trouve ici. Il s’agit d’un changement qui a eu lieu pour pandoc 2.0 qui est passé de la commande --latex-engine=xelatex à la commande --pdf-engine=xelatex. Pour résoudre ce problème, remplacez simplement l’occurrence dans la ligne de commande pandoc que vous trouverez dans Paramètres > Paramètres avancés. Ou bien installez la dernière version de pandoc.

Attention (bis) : Dans les options du PDF, section Police sont indiquées les polices de caractères que pandoc utilisera pour la transformation en PDF via XeLaTeX. Si vous ne les avez pas sur votre système, un message d’erreur sera affiché. Indiquez à cet endroit les polices de caractères que vous souhaitez utiliser.

Les autres formats

Zettlr permet de faire des présentations en markdown puis de les exporter en utilisant reveal.js. Il vous reste donc à rédiger votre présentation et choisir parmi les modèles proposés (couleurs dominantes).

Vous pouvez aussi exporter directement en HTML : pour cela Zettlr dispose d’un modèle et exportera votre document en une page HTML contenant aussi les styles (on dit « standalone » ou option -s avec pandoc).

Quand aux autres formats, le choix reste intéressant :

Format	Destiné pour
HTML	Navigateur
.ODT	Traitement de texte type LibreOffice, MSWord, AbiWord, etc.
.DOCX	Microsoft
rST	ReStructuredText : mise en forme pour de la doc de langage type Python
RTF	Rich Text Format : format descriptif pour traitement de texte
TeX	Format pour TeX / LaTeX
TXT	Format texte (simple)
ORG	Pour Emacs Org (pour les utilisateurs d’org-mode, très puissant
Bdl / Pck	TextBundle (un conteneur markdown + description + fichiers liés) / Variante

… il manque selon moi la possibilité d’exporter en .epub, un tâche dont s’acquitte très bien pandoc et qui pourrait avoir son application pour l’écriture de livre, lorsqu’on a plusieurs chapitres dans des fichiers séparés. Peut-être que cette fonctionnalité sera ajoutée ultérieurement.

Conclusion

Zettlr est un excellent logiciel qui tire de nombreux avantages du markdown dans le flux de production de documents longs et dans la gestion de documentation personnelle. Il pêche encore par manque de pédagogie, mais il est sur la bonne voie. Par ailleurs, sur les aspects qui concernent l’exportation, ce que propose Zettlr est une interface graphique de pandoc. Les habitués de al ligne de commande, comme moi, ne seront pas franchement épatés : j’estime qu’il à ce niveau plus important d’apprendre à complètement se servir de pandoc. Et s’il lui faut une interface graphique (et je pense que ce serait plutôt bien), dans ce cas, je préférerais largement un programme uniquement dédié aux fonctions de conversion de pandoc (et pas au markdown).

Des directions devront être envisagées en fonction du public visé pour Zettlr. Par exemple, au vu de son fonctionnement global, il pourrait tout à fait être utilisé en binôme avec Git et par conséquent intégrer des options spécialisées dans le versionning. Une autre possibilité consisterait à utiliser une connexion à un dépôt Nextcloud afin de pouvoir synchroniser facilement l’écriture de documents en markdown. Bien sûr, qu’il s’agisse de Git ou de Nextcloud, il est déjà possible soit de commiter les fichiers à part, soit de travailler dans un dossier distant, mais il s’agit-là de tâches spécialisées avec lesquelles tout le monde n’est pas familier.

Rédiger et manipuler des documents avec Markdown

situveuxmonadresse@demande-la.moi (Christophe Masutti) — Tue, 28 May 2019 00:00:00 +0000

Rédiger des documents et élaborer un flux de production implique d’envisager clairement le résultat final. Formulé ainsi, cela pourra toujours sembler évident : que voulez-vous faire avec votre document ? À qui le destinez-vous ? Pour quels usages ? Après avoir livré quelques considérations générales relatives à la stratégie j’expliquerai comment j’envisage la rédaction de documents (souvent longs) avec Markdown vers ODT ou LaTeX.

Quelques considérations préalables

Rédiger un document avec LibreOffice, MSWord, LaTeX (ou d’autres logiciels de traitement de texte) c’est circonscrire le flux de production aux capacités de ces logiciels. Attention, c’est déjà beaucoup ! Les sorties offrent bien souvent un large choix de formats selon les besoins. Cela dit, une question peut se poser : ne serait-il pas plus logique de séparer radicalement le contenu du contenant ?

Après tout, lorsqu’on rédige un document avec un logiciel de traitement de texte, chercher à produire un format compatible consiste à produire un format qui sera non seulement lisible par d’autres logiciel et sur d’autres systèmes, mais aussi que sa mise en page soit la même ou quasi-similaire. Finalement, on veut deux choses : communiquer un format et une mise en page.

Voici quelques années que je fréquente différents logiciels dans le cadre de la rédaction et de l’édition de documents, à commencer par LibreOffice et LaTeX. Compte-tenu des pratiques actuelles de stockage dans les nuages et la sempiternelle question du partage de documents et de la collaboration en ligne, j’en suis arrivé à une conclusion : écrire, manipuler, partager, modifier un document déjà mis en forme par un logiciel de traitement de texte est une erreur. Les formats utilisés ne sont que très rarement faits pour cela (il y a bien sûr des exceptions, comme le XML, par exemple, mais nous parlons ici des pratiques les plus courantes).

Tous les formats propriétaires sont à bannir : leur manipulation est bien trop souvent source d’erreur, et suppose un enfermement non seulement de la chaîne de production mais aussi des utilisateurs dans un écosystème logiciel exclusif. Sitôt qu’un écart minime se forme dans cette chaîne, c’est fichu.

Les formats ouverts sont bien plus appropriés. Justement parce qu’ils sont ouverts, leur compatibilité pose d’autant moins de souci. Il subsiste néanmoins toujours des risques lorsque des logiciels propriétaire entrent dans la chaîne de production parce que tous les utilisateurs n’ont pas les mêmes outils.

La faiblesse ne concerne pas uniquement ces formats ou ces logiciels mais elle réside aussi dans leur manipulation. Même si on accepte de travailler (au prix de nos libertés et de notre confidentialité) avec des services comme ceux de Google ou Microsoft, et même si on utilise des solutions libres et ouvertes comme OnlyOffice ou LibreOffice Online, l’enjeu auquel nous faisons toujours face est le suivant : en ligne ou en local, choisir un logiciel de traitement de texte revient à restreindre d’emblée l’usage futur de la production en choisissant par avance son format final et sa mise en page.

Faire ce choix n’est pas interdit (et heureusement !). C’est d’ailleurs celui qui prévaut dans la plupart des situations. Il faut seulement l’assumer jusqu’au bout et manœuvrer de manière assez efficace pour ne pas se retrouver « coincé » par le format et la mise en page choisis. Là aussi, il faut réfléchir à une bonne stratégie de production et conformer toute la chaîne au choix de départ.

D’autres solutions peuvent être néanmoins adoptées. Au même titre que la règle « faites votre mise en page en dernier » doit prévaloir pour des logiciels wysiwyg, je pense qu’il faudrait ajouter un autre adage : « choisissez le format le plus basique en premier ». Cela permet en effet de produire du contenu très en amont de la phase finale de production et inclure dans cette dernière la production du format à la demande.

Quels choix ?

En d’autre termes, si votre éditeur, votre directeur de thèse, vos collègues ou vos amis, vous demandent un .odt, .doc, un PDF, un .epub, un .texou un .html, l’idéal serait que vous puissiez le produire à la demande et avec une mise en page (ou une mise en forme s’il s’agit d’un document .tex, par exemple) différente et néanmoins appropriée. Pour cela, il faut impérativement :

connaître une méthode sûre pour convertir votre document,
connaître les possibilités de mise en forme automatiques à configurer d’avance pour produire le document final.

Autrement dit, avant même de commencer à produire votre contenu (que vous allez détacher absolument de la forme finale), vous devez élaborer tout un ensemble de solutions de conversion et de mise en forme automatiques.

Rien de bien nouveau là-dedans. C’est exactement la même stratégie que l’on emprunte lorsqu’on rédige un contenu le formatant à l’aide d’un langage balisé comme le HTML ou (La)TeX. On ne fait alors que produire un document texte formaté et, parallèlement, on crée des modèles de mise en page (.css pour le HTML, ou des classes .cls pour LaTeX). La sortie finale emprunte alors les instructions et les modèles pour afficher un résultat.

L’idée est d’adopter cette démarche pour presque n’importe quel format. C’est-à-dire :

créer du texte à l’aide d’un éditeur de texte et choisir un langage de balisage facile à l’utilisation et le plus léger possible : le Markdown est à ce jour le meilleur candidat ;
convertir le document en fonction de la demande et pour cela il faut un convertisseur puissant et multi-formats : Pandoc ;
créer des modèles de mise en page (pour les réutiliser régulièrement si possible).

Avantages

Les avantages de Markdown sont à la fois techniques et logistiques.

D’un point de vue technique, c’est sur la syntaxe que tout se joue. Comme il s’agit d’un balisage léger, le temps d’apprentissage de la syntaxe est très rapide. Mais aussi, alors qu’on pourrait considérer comme une faiblesse le fait que Markdown ne soit pas standardisé, il reste néanmoins possible d’adapter cette syntaxe en lui donnant un saveur particulière. C’est le cas de Multimarkdown, une variante de Markdown permettant des exports plus spécialisés. Ainsi, plusieurs fonctionnalités sont ouvertes lorsqu’on destine un document Markdown à la conversion avec Pandoc. On retient surtout les tables, les notes de bas de page et la gestion bibliographique ou d’index. Enfin, il est toujours possible d’inclure du code HTML ou même LaTeX dans le document source (parfois même les deux, en prévision d’une conversion multiple).

Pour ce qui concerne le travail Markdown + Pandoc + LaTeX, on peut se reporter à l’article que j’avais traduit sur ce blog : « un aperçu de Pandoc ».

Pour ce qui concerne la pérennité d’un fichier markdown, tout comme n’importe quel fichier texte, il sera toujours lisible et modifiable par un éditeur de texte, ce qui n’est pas le cas des formats plus complexes (exceptés les formats ouverts).

D’un point de vue logistique, la manipulation a plusieurs avantages, bien qu’ils ne soient pas réservés au seul format Markdown :

les éditeurs de texte sont des logiciels très légers par rapport aux « gros » logiciels de traitement de texte, si bien que travailler sur un document Markdown ne nécessite que peu de ressources (et il y a un grand choix d’éditeurs de texte libres),
on peut aisément travailler à plusieurs sur un document texte en utilisant des services en ligne légers comme des pads (par exemple sur framapad.org ou cryptpad),
ce qui n’empêche pas l’utilisation de logiciels en ligne plus classiques, pourvu que l’export puisse se faire en texte ou dans un format qui permet la conversion « inverse » vers le Markdown (ou alors de simples copier/coller),
on peut utiliser facilement un dépôt Git pour synchroniser ses fichiers et retrouver son travail où que l’on soit (ou collaborer avec d’autres utilisateurs),
le fait de séparer le contenu de la forme permet de se concentrer sur le contenu sans être distrait par les questions de mise en page ou une interface trop chargée (c’est aussi un argument pour LateX, sauf que la syntaxe plus complexe contraint en fait le rédacteur à organiser son texte selon les critères « logiques » de la syntaxe, ce qui est aussi respectable).

Mon système à moi

J’en avais déjà parlé dans un autre billet sur Markdown, Pandoc HTML et LaTeX, aussi il y aura des répétitions…

J’utilise LibreOffice ou LaTeX ou la HTML en seconde instance. Dans la mesure du possible j’essaie de rédiger d’abord en Markdown, puis de convertir.

Je procède ainsi dans les cas de figure suivants (liste non exhaustive) :

la rédaction d’un billet de blog (inutile de convertir car mon moteur de blog utilise le Markdown et converti tout seul en HTML),
la rédaction de notes (pour une réunion ou un texte court) que je converti en PDF en vue d’une diffusion immédiate,
la rédaction d’un document long que je produirai en PDF via LaTeX,
la rédaction d’un document long que je produirai en HTML et/ou epub,
la rédaction d’un document long que convertirai en ODT dans le cadre d’un projet éditorial,
la rédaction d’un article que je destine à une diffusion en HTML et/ou epub.

Pour convertir avec Pandoc, la moulinette de base est la suivante (ici pour du .odt) :

pandoc fichier-de-depart.md -o fichier-de-sortie.html

Ensuite tout est une question d’ajout d’options / fonctions dans la ligne de commande.

Les difficultés sont les suivantes (je ne reviens pas sur le mode d’emploi de Pandoc, l’usage des templates, etc.).

Les styles

La gestion des styles dans la conversion en .odt dans LibreOffice n’est pas évidente. Le mieux est encore d’utiliser un modèle qui prenne en compte les styles que Pandoc produit lors de la conversion. En effet, la grande force de LibreOffice, ce sont les styles (voir cet ouvrage). Dès lors il est important que vous puissiez opérer dessus une fois votre document au format ODT.

Pour faire simple, il n’est pas utile de spécifier un modèle lors de la conversion avec Pandoc. Il faut la plupart du temps se contenter de produire le document en .odt puis appliquer les styles voulus. Pour aller vite, voici ce que je conseille de faire :

rédigez une fois un document Markdown avec toutes les marques de formatage que vous voulez,
convertissez-le en .odt,
ouvrez le .odt avec LibreOffice et modifiez les styles que Pandoc a créé,
sauvegardez ce document,
puis à chaque fois que vous devrez produire un document similaire, effectuez un simple transfert de style en suivant la méthode expliquée pages 64-66 de cet ouvrage.

Pour gérer les styles en vue d’une production de document HTML/epub ou LaTeX/PDF, le mieux est encore de créer ses classes .css et/ou .cls et/ou .sty et d’y faire appel au moment de la conversion. On peut aussi intégrer l’appel à ces fichiers directement dans le template, mais faut dans ce cas donner leur nom, ce qui n’est pas pratique si l’on souhaite avoir plusieurs styles de mise en page à disposition et changer à la volée.

Par exemple, pour une sortie HTML :

pandoc --template=modele.html -H monstyle.css fichier-de-depart.md -o fichier-de-sortie.html

(notez que l’appel au fichier .css peut très bien être déjà inclus dans le modèle)

La bibliographie

J’ai indiqué dans cet article comment utiliser Pandoc avec une bibliographie. L’essentiel est de comprendre que, quel que soit le format de sortie choisi, il faut que votre bibliographie soit enregistrée dans le format de bibliographie par excellence, bibtex (.bib). Puis :

si vous voulez sortir un fichier pour LaTeX, la bibliographie se gérera avec Biblatex (on ajoutera l’option --biblatex dans la ligne de commande),
si vous voulez sortir des fichiers HTML, ou ODT, avec une mise en forme de la bibliographie, il faut aussi installer Citeproc, un jeu de programmes auxquels Pandoc fera appel pour appliquer des instructions de configuration en CSL Citation Style Language.

Concernant les styles de bibliographie obtenus en CSL, le mieux est encore d’utiliser le logiciel Zotero. Il peut vous servir à créer votre bibliographie (il est très pratique grâce à son extension pour Firefox) ou simplement ouvrir votre .bib obtenu par un autre logiciel, peu importe. Comme Zotero permet d’exporter des éléments bibliographiques formatés, il permet aussi de jouer avec les styles CSL disponibles sur ce dépôt. Si vous trouvez votre bonheur, conservez le fichier .csl de votre style ou bien utilisez l'éditeur en ligne pour en créer un de toutes pièces ou modifier un modèle existant.

Notez que la conversion vers le format .odt avec une bibliographie formatée avec un modèle .csl ne vous produira pas une bibliographie comme si vous l’aviez obtenu avec l’extension Zotero dans LibreOffice et des références dynamiques. Au contraire, selon la mise en forme choisie vous aurez vos éléments bibliographiques dans votre document (y compris avec une bibliographie à la fin) mais il faudra re-compiler si vous changez des éléments bibliographiques. N’oubliez pas que vous devez prendre en compte toute la chaîne depuis votre format de départ (c’est pareil avec LaTeX : il faut recompiler si on met la biblio ou l’index à jour).

Git : travailler dans l’cloude

Comme il m’arrive tous les jours d’utiliser au moins deux ordinateurs différents, j’ai choisi d’utiliser Git lorsque je dois rédiger des documents longs sur une longue période de temps. Là encore, l’avantage d’utiliser de simples fichiers texte, permet de jouer sur la rapidité et la flexibilité de Git. On peut aussi se payer le luxe (selon les programmes disponibles sur le serveur) de configurer des jobs qui permettent, une fois uploadé(s) le(s) fichier(s) Markdown, de créer automatiquement les sorties voulues. Si Pandoc est installé, vous pouvez une fois pour toute configurer votre dépôt pour créer l’artefact à chaque fois.

il est donc inutile de s’encombrer localement (et encombrer le dépôt avec) des fichiers de sortie à moins de les tracer avec Git LFS (cf. ci-dessous).

Concernant les fichiers binaires, trop volumineux, les illustrations, etc. , il faut utiliser GIT LFS qui permet de trier et tracer les fichiers qu’il est inutile de recopier en doublon à chaque fois sur le serveur.

Choisir un bon éditeur

Non, il ne s’agit pas de l’éditeur de la collection où vous allez publier votre livre. Il s’agit de l’éditeur de texte.

Pour ceux qui sont habitués à utiliser à chaque fois un logiciel de traitement de texte wysiwyg pour écrire, il pourrait à première vue sembler bien austère de choisir un logiciel avec une interface moins fournie (en apparence, en tout cas) pour écrire. Et pourtant, que de tranquillité ainsi gagnée !

Tout d’abord un bon éditeur est un éditeur avec coloration syntaxique. Avec cela, les éléments importants de la syntaxe Markdown, ainsi que les titres, les mots en italique, etc., apparaissent en évidence. Ensuite, un bon éditeur de texte est presque entièrement configurable : il vous sera très bénéfique de configurer selon vos goûts le thème de la coloration syntaxique et de l’interface, ainsi que la police. Cela vous assurera surtout un confort d’écriture.

Certains éditeurs sont spécialisés en Markdown, tel Ghostwriter. Mais vous pouvez toujours utiliser des éditeurs destinés à la programmation mais disposant de tout ce qu’il faut pour écrire en Markdown. Certains sont de véritable machines à tout faire (et intègrent souvent une extension pour gérer un dépôt Git), tel Atom ou Geany, d’autres sont des éditeurs de textes historiques du Libre, plus difficiles au premier abord, comme Vi ou Emacs (et avec un grand choix d’extensions). Et il y a ceux qui sont beaucoup plus simples (Gedit, Kate, Notepad++).

Inutile ici de s’étendre sur les centaines d’éditeurs de texte libres et disponibles pour tout un chacun. L’essentiel est de comprendre qu’un bon éditeur est d’abord celui qui conviendra à votre usage et qui vous permettra d’écrire confortablement (esthétique et ergonomie).

Quels outils de production ?

Pour terminer ce billet, voici les éléments pour créer mon flux de production (du moins celui auquel je me conforme le plus possible).

Format	Outils	Fichiers	Résultats
Markdown	Pandoc + biblatex	`.md`, `.bib`, template `.tex`, `.cls`, `.sty`	TeX (et PDF)
Markdown + .bibtex	Pandoc + CSL	`.md`, `.bib`, `.csl`, `.css`, template `.html`	HTML
Markdown + .bibtex	Pandoc + CSL	`.md`, `.bib`, `.csl`	ODT

Logiciels utilisés :

éditeurs : Gedit, Ghostwriter, Atom, Zettlr (cela dépend de mon humeur) ;
Pour synchroniser et stocker en ligne : Git et Gitlab, ou bien une instance Nextcloud ;
LaTeX (éditeur de texte classique ou Texmaker) ;
LibreOffice pour un traitement de texte autre que LaTeX ;
JabRef et Zotero pour la gestion bibliographique (parfois un simple éditeur de texte).

Concernant la rédaction d’un ouvrage à paraître bientôt, voici comment j’ai procédé tout au long du processus d’écriture :

rédaction des parties (un fichier par partie) en Markdown avec Ghostwriter la plupart du temps (il dispose d’un outil de visualisation de table des matières fort pratique) ;
Zotero ouvert sans interruption pour entrer les références bibliographiques au fur et à mesure et insérer leurs IDs dans le document en référence ;
synchronisation à chaque fin de session de travail avec Git (une instance Gitlab), et une requête de récupération à chaque début de session ;
pour donner à l’éditeur un « manuscrit » en ODT suivant ses prescriptions : conversion avec Pandoc et un fichier CSL pour la bibliographie : la collaboration avec l’éditeur se fera sur Libreoffice (mise en forme, suivi de corrections).
à venir : récupération du travail fini en Markdown et export HTML/epub pour la postérité.

Ajoutons à cela que l’usage du Markdown tend à se prêter à bien d’autres situations. Ainsi ce blog est écrit entièrement en Markdown, mes courriels le sont parfois, le logiciel qui me permet de prendre des notes et de les synchroniser sur un serveur utilise le Markdown (j’utilise alternativement Joplin ou Notes de Nextcloud, et de temps à autre Firefox Notes). En somme, autant de situations qui me permettent d’écrire, synchroniser et exporter : le Markdown est omniprésent.

Ghostwriter, un bon éditeur Markdown

situveuxmonadresse@demande-la.moi (Christophe Masutti) — Thu, 01 Jun 2017 00:00:00 +0000

Après plusieurs essais pour trouver l’éditeur Markdown qui convienne à mes besoins, je pense avoir trouvé avec Ghostwriter une réponse plutôt pertinente.

Ghostwriter mise avant tout sur la simplicité. C’est ce qu’on appelle un éditeur « distraction free ». Il pousse même le concept jusqu’à proposer trois mode d’édition :

un mode normal,
un mode « focus » qui permet de mettre en surbrillance la phrase (et non la ligne) que l’on est en train d’écrire (jusqu’à la ponctuation, en fait),
un mode « Hemingway », qui désactive les touches backspace et delete pour se forcer à écrire comme avec une antique machine à écrire mécanique.

Mais cela, c’est du détail. Dans les fonctions plus opérationnelles, on note :

une interface en panneaux, qui permet de passer le panneau principal où l’on écrit en mode plein écran, vraiment « distraction free »,
la possibilité d’insérer des images en glisser-déposer directement dans l’interface,
des fenêtres HUD (affichage tête haute, en anglais : Head-up display) qui permettent de sortir notamment l’affichage du sommaire du document et les statistiques.
Parmi les statistiques, on note aussi quatre types d’estimation : la durée de lecture, le pourcentage de mots complexes, et de manière corrélée la facilité de lecture et le niveau (facile, université, très difficile…). Tiens en écrivant le terme « corrélé » ci-dessus, je suis passé à « difficile », j’espère que cela ira…
enfin, un autre panneau permet d’afficher le rendu HTML du document.

Concernant le rendu, une fonction très appréciable est le choix des rendus en fonction des moteurs de transcription de la saveur Markdown utilisée. Ainsi le rendu intègre le choix d’un rendu à la sauce Pandoc, Sundow, Multimarkdown, etc. Une autre fonction est le choix de la CSS qui servira à la fois pour le rendu en temps réel mais aussi pour une éventuelle exportation en HTML.

À propos d’export, le choix est très large et on doit souligner la grande propreté des fichiers produits : html, html5, odt, xml, rtf, docx, pdf (LaTeX), pdf (ConTeXt), epub2, epub3, Groff, LaTeX… Pour ce qui me concerne, j’exporte très souvent en LaTeX, en choisissant le moteur Pandoc, et c’est vraiment efficace. Évidemment l’autre solution est d’enregistrer le .md et le convertir avec Pandoc en ligne de commande.

Le reste est à l’avenant : correction orthographique, interface en plusieurs langues, personnalisation assez poussée de l’apparence de l’interface (couleurs, transparence, image d’arrière plan). Ces sont autant de petits détails qui rendent l’utilisation de Ghostwriter fort appréciable.

Pour conclure, Ghostwriter répond à mes attentes, parce qu’il situe une bonne interface de rédaction à l’intersection entre l’éditeur de texte et les sorties souhaitées pour la finalisation (LaTeX et HTML, surtout pour ce qui me concerne).

Lien vers le site officiel de Ghostwriter : wereturtle.github.io/ghostwriter/