Cet article a été inspiré par celui de Benoît Benedetti, Administrateur Système Linux à l’Université de Nice Sophia Antipolis, « AsciiDoc et AsciiDoctor pour soigner votre documentation », dans « Gnu/Linux Magazine France » n° 190 de février 2016. Il fait suite à un précédent dont la lecture pourra aussi être utile.
Créer un texte selon sa destination
La création d’un document informatique comporte deux étapes :
– étape nécessaire : la saisie du texte ;
– étape facultative : sa mise en forme pour publication, au moyen d’indications typographiques telles que styles de caractères, de mise en page, création de tables et d’index, etc.
Les logiciels de la famille Word confondent ces deux étapes en incorporant les indications de mise en forme dès l’étape de saisie du texte, ce qui a pour inconvénient de donner une mise en forme en général assez laide, notamment parce qu’elle opère ligne par ligne, sans tenir suffisamment compte de l’équilibre général de la page. En outre, ce mode opératoire rend ces logiciels totalement inappropriés à la saisie de programmes ou de données informatiques, types de texte pour lesquels on ne veut surtout pas de fioritures typographiques.
Avec des langages de description de documents tels que LaTeX, Html, DocBook, Markdown ou AsciiDoc, les deux étapes sont clairement séparées :
– La saisie du texte est effectuée au moyen d’un logiciel qui ne fait que cela, l’enregistrement de la saisie, et que l’on nomme éditeur de texte. L’auteur de ces lignes utilise Emacs, perfectionné mais assez compliqué, il en existe de très simples, tels que Notepad++ ou Nano, ou encore Vim si l’on a vraiment des problèmes ontologiques. Et pour saisir un texte de programme informatique, on en reste là, la prochaine étape sera la compilation du programme par... un compilateur du langage utilisé.
– Si le texte est destiné à la publication pour des humains, les indications typographiques sont inscrites dans le document par son auteur, sous la forme de balises. Le document source ainsi instrumenté sera ensuite traité par un logiciel de mise en forme capable d’interpréter les balises : pour des balises LaTeX ce sera par exemple xelatex
ou lualatex
, pour des balises Html ce sera votre navigateur Web, pour des balises AsciiDoc j’aime bien AsciiDoctor, plus perfectionné qu’AsciiDoc.
Publier un document lisible
Pour créer un document destiné à être imprimé, surtout s’il s’agit d’une publication par un véritable éditeur de livres ou de revues, il y a trois familles de solutions :
- les mauvaises : Word et ses succédanées libres ;
- les bonnes : LaTeX (surtout sous des formes modernes XeLaTeX et LuaLaTeX) ;
- les compromis acceptables, plus faciles à apprendre que LaTeX et moins moches que Word, qui appartiennent principalement à deux familles plus restreintes et d’ailleurs cousines : DocBook d’un côté, de l’autre Markdown et ses neveux AsciiDoc et AsciiDoctor, qui seront l’objet de cet article.
Régulièrement je suis amené à travailler avec des utilisateurs de Windows, pour rédiger une page Web, un énoncé d’exercices de TP, voire un article ou un livre, cela se finit toujours par un échange de documents Word, c’est improductif et horripilant. En outre, souvent, le logiciel qui a servi à cet usage est volé, ce qui est mal.
Ainsi, créer un texte : un jour un lecteur de mon manuel de programmation m’a reproché de ne pas avoir expliqué comment on créait le texte d’un programme. Rétrospectivement, je suis encore offusqué de cette remarque, mais je devrais plutôt la considérer comme le symptôme des dégâts intellectuels provoqués par la généralisation des interfaces graphiques, les cliquodromes, qui sont bien destinés à ne pas faire d’informatique mais à utiliser celle que d’autres ont faite. Mon père et mon grand-père, littéraires à l’état pur, se donnaient la peine de comprendre le fonctionnement des machines à vapeur, des centrales hydro-électriques et des fours Martin, ils avaient du mal mais ils en faisaient l’effort, il me semble que les non-informaticiens d’aujourd’hui pourraient entreprendre une démarche analogue, d’autant mieux que c’est plus facile à comprendre.
Donc, créer un texte : contrairement à l’opinion de plus en plus répandue, cela ne se fait pas avec Word ou un de ses succédanées, LibreOffice, OpenOffice ou Google Docs, qui sont des logiciel de traitement de texte, mais avec un éditeur de texte. Dans le monde informatique les éditeurs les plus convenables se nomment Emacs, vi ou ed, qui soit dit en passant existent sous Windows, mais qui sont sans doute d’un emploi rebutant pour la victime des cliquodromes. Aussi existe-t-il des outils d’un usage plus facile.
Notepad++
Tout système Windows vient avec un logiciel nommé Notepad, destiné à cet usage, mais en fait peu pratique, et WordPad n’est pas meilleur. L’utilisateur de Windows qui n’aura pas encore sauté le pas et installé Emacs trouvera son bonheur avec l’excellent Notepad++, qui lui permettra de créer simplement toutes sortes de documents, y compris des programmes correctement indentés, ce qui est la première condition de leur justesse [1] (il y a même un style Scheme qui met bien les mots-clé en couleur, les parenthèses alignées et tout et tout). C’est vraiment un bon outil, installé en deux minutes, et doté de toutes les fonctions nécessaires tout en restant facile d’usage.
De grâce, pour tout ce qui n’est pas destiné à une mise en page avec polices et styles, laissez Word et ses congénères, vive Notepad++ !
Ruby
Une fois que l’on sait créer des textes simplement, sans toutes les complications de Word/LibreOffice/OpenOffice, on aimerait bien pouvoir en faire une page HTML, ou un document PDF, ou même un document LaTeX. C’est possible avec AsciiDoc, ou aussi AsciiDoctor. Ces deux logiciels utilisent le même format très simple pour décrire la mise en page, AsciiDoc est peut-être plus rapide à installer sous Windows et peut produire du HTML (4 ou 5), du DocBook, du LaTeX, des planches de présentation et du WordPress. AsciiDoctor produit les mêmes formats, plus du PDF : un moyen simple de produire du PDF, cela ne se refuse pas, alors ce sera AsciiDoctor, mais avant d’installer AsciiDoctor il faut installer Ruby, ce qui fait l’objet de la présente section.
Le moyen le plus simple d’installer Ruby sous Windows me semble RubyInstaller. Alors allons-y : une fois l’installateur téléchargé c’est l’affaire de quelques secondes. Ruby se lance dans la fenêtre de terminal moche de Windows, c’est Windows, pour vous dégoûter de l’informatique, mais là c’est pour la bonne cause alors on continue.
Sous Linux, les versions de Ruby disponible dans les dépôts sont désormais suffisamment récentes pour supporter AsciiDoctor.
Installation de AsciiDoctor
Sous Windows c’est très simple (expliqué ici aussi), dans la fenêtre de texte qui s’ouvre lorsque l’on lance Ruby, taper :
gem install asciidoctor
Sous Linux :
sudo apt-get install asciidoctor asciidoctor-doc
Puis on peut installer les outils qui produisent les différents formats de sortie :
sudo gem install asciidoctor-pdf
sudo gem install asciidoctor-latex
À noter que l’option --pre
, qui pourrait figurer derrière le mot install
, peut être ou ne pas être nécessaire, en fonction de la sortie de nouvelles versions. Si cela ne marche pas avec, essayer sans, ou réciproquement.
Mise en page AsciiDoc
Ce qui est séduisant avec le format AsciiDoc, c’est qu’il est simple et pourtant riche de possibilités.
C’est un langage de balises, comme LaTeX ou Html, et à l’inverse de Word/LibreOffice/OpenOffice/Google Docs, c’est-à-dire que les indications de mise en forme figurent dans le texte lui-même, sous une forme syntaxique qui les distingue du texte destiné à la publication. Voici un exemple :
On distingue facilement la syntaxe, en tête, des attributs, ou métadonnées, coderay
est le nom d’un style de mise en forme à installer ainsi :
Les noms des autres attributs ne prêtent pas à confusion.
On trouvera sur le site AsciiDoc la description complète de la syntaxe. Ou, plutôt mieux à mon avis, sur le site AsciiDoctor.
Produire un document
Une fois que le système de production est installé et que l’on a saisi son document avec Notepad++, on peut le produire au format désiré :
asciidoctor -r asciidoctor-pdf -b pdf mon-document.adoc
asciidoctor -r asciidoctor-latex -b latex mon-document.adoc
ou, plus simplement, pour une sortie Html :
asciidoctor mon-document.adoc
Convertir au format docx de Word
Beaucoup d’éditeurs demandent une copie lisible par Word, au format docx. AsciiDoctor ne le fait pas directement, il faut passer par un format intermédiaire xml (en l’occurrence docbook), que l’on convertit ensuite avec pandoc :
asciidoctor -b docbook mon-document.adoc
pandoc --from docbook --to docx --output mon-document.docx mon-document.xml
Le document Word résultant sera considéré comme étant en langue anglaise, et de ce fait le correcteur affichera des erreurs pour la plupart des mots. C’est facile à corriger : l’entrée « Langue » du menu « Outils » permet de choisir la langue du document, si tel est le cas on peut préciser qu’il est en français.
Personnaliser le style, colorier le code
Pour personnaliser les sorties LaTeX, les préambules par défaut sont ici (pour une installation standard sous Ubuntu) :
/var/lib/gems/2.3.0/gems/asciidoctor-latex-1.5.0.17.dev/
ou, sur une autre installation, ici :
/usr/local/lib/ruby/gems/2.3.0/gems/asciidoctor-latex-1.5.0.17.dev/data/
:
La sortie par défaut est en Html. On peut aussi avoir du code colorié en fonction de la syntaxe (jointe à cet article la feuille de style pour Scheme, que j’ai écrite à partir de celle de Clojure) :
Pour une installation à partir du site Ruby les fichiers de style selon les langages sont ici :
À partir des paquets Ubuntu :
Sous Windows :
Le résultat n’est pas mal, en Pdf comme en Html, je ne saurais trop vous conseiller ces logiciels d’usage aisé pour de bons résultats.
Voici les résultats :
J’ai écrit assez facilement un style Scheme à partir de celui de Clojure, il suffit d’ajouter les mots-clé souhaités. Dans le texte des programmes, l’indentation doit être réalisée au moyen d’espaces, pas de tabulations : remplacer chaque caractère de tabulation par 8 espaces donne le résultat désiré. Voici le corps de la sortie Html :
Annoter un document PDF, remplir un formulaire PDF ou JPG
Les versions récentes d’Acrobat Reader permettent d’annoter un document PDF ou de remplir un formulaire (administratif par exemple). Mais la maison Adobe a décidé de punir les utilisateurs de logiciels libres, et ces versions récentes n’existent pas sous Linux.
C’était sans compter... sur la créativité de la communauté du logiciel libre ! Le logiciel libre Evince permet d’annoter un document PDF, et ces annotations sont lisibles par Acrobat Reader, ce qui est commode, par exemple, pour corriger les épreuves d’un manuscrit. Mais il reste encore des obstacles, tous les formulaires ne sont pas accessibles, et l’administration française s’illustre fâcheusement en produisant des documents Cerfa qui ne peuvent être remplis que sous le joug de Windows ou de macOS.
Il existe encore une autre solution pour contourner les barrières : le logiciel libre et gratuit Inkscape (disponible pour Windows, macOS et GNU/Linux), permet d’une part d’écrire sur un document PDF (ou JPG) pour remplir des rubriques, d’autre part d’y coller une signature scannée et enregistrée au format PNG, puis d’enregistrer le tout au format PDF. Inkscape permet d’écrire sur à peu près n’importe quel type de document.