Asciidoc

La rédaction documentaire

Quiconque vous le dira, dans l’IT, le référentiel documentaire d’un projet est toujours le vilain petit canard, un mal aimé lorsque faut le rédiger mais qui pourtant fait l'unanimité des critiques lors de son absence.

Le but de cet article n’est pas forcement de vous convaincre de son utilité et de sa nécessité et de vous réconcilier (on tentera cela dans un autre article)  avec mais juste de vous présenter un outil qui peut être pourra vous simplifier la vie: Asciidoc [1].

Asciidoc est un outil de génération de doc sous différents format à base d’un langage simple inspiré des syntaxes employés dans les Wiki. Cela le rend très facile d'access.

Alors bien sur il n’est pas le seul dans ce domaine, on pourrait parler par exemple de markdown [2], [7] ou latex [3]. Peut être le feront nous seulement j’ai souhaité parler de asciidoc car il m’à semblé être un bon compris justement entre ces deux autres outils :

• markdown étant vraiment très basique voir simpliste, Asciidoc vous donnera plus d’expressivité tout en fournissant un rendu très satisfaisant. 
• latex à l’inverse est complet et fournira toujours des résultats impeccables c’est certain pourtant, acquérir sa maîtrise demande une marche qui sera moins haute avec Asciidoc.

Installation

Asciidoc est un outil développé en Python (on se chargera d’installer python 27 préalablement donc). Pour bénéficier de sa dernière version, rien de plus simple:

• un téléchargement sur sourceforge, 
• un dezip 
• un alias dans votre bashrc (sous Debian ou Cygwin) et on est parti!

alias ascdoc="/cygdrive/c/Python27/python.exe C:/Tools/asciidoc-8.6.9/asciidoc.py"

L’outils est divisé en deux applications principales:

• asciidoc : permettant de transformer les fichiers asciidoc en html ou DocBook
• a2x : outil plus générique pour convertir les fichiers asciidoc en d’autres formats comme latex, epub, etc… on ne s’attardera pas spécialement sur celui ci.

Pour utiliser le premier, on l'appellera en ligne de commande comme ceci:

python ../asciidoc.py -b docbook asciidoc.txt

ou avec l’alias

ascdoc -b docbook asciidoc.txt

Et pour faire une présentation, il faut utiliser le backend slidy.

ascdoc -d slidy -b docbook asciidoc.txt

Premier document

Bien maintenant que nous avons quelques base, essayons de produire un premier document, une présentation rapide de Asciidoc.

Pour cela nous allons directement nous appuyer sur cet article et nous verrons dans la présentation quelques éléments du langage permettant de construire la dite présentation [6].

Pour la consulter, je vous invite à la consulter ici [4].
Pour en voir le code source complet d’aller ensuite ici [5].

Premier constat, c’est simple et plutôt clair par défaut. Seul bémol, c’est peut être un peu trop simple. On aimerait avoir quelque chose de moins statique et un peu plus jolie, c’est vrai. Après on en a pour son argent, avec une commande simple, on à quelque chose de rapide et clair!

Conclusion

Voilà nous avons passé en revue rapidement et simplement l’utilisation de Asciidoc et vue un prototype de présentation. Dans l’objectif de création de documentation, il me semble que cet outil est réellement pertinent car permettant à moindre coût d’apprentissage de produire des supports suffisamment structurés pour être exploité dans un projet. Dans un article prochain nous regarderons s’il n’est pas possible de l'étendre ^^.

Références

[1] http://asciidoc.org/
[2] https://openclassrooms.com/fr/courses/1304236-redigez-en-markdown
[3] https://www.latex-project.org/
[4] https://collonville-tom.github.io/tc-un-est-tout-et-tout-est-un/asciidoc-article/ascii-article.html#(1)
[5] https://github.com/collonville-tom/tc-un-est-tout-et-tout-est-un/blob/master/docs/asciidoc-article/ascii-article.adoc
[6] https://www.methods.co.nz/asciidoc/userguide.html
[7] https://asciidoctor.org/docs/asciidoc-vs-markdown/