AsciiDoc est un langage de balisage agile, capable de transcrire un document accompagné d’une syntaxe simple et naturelle vers un document destiné aux pages Web ou à l’impression, en s’affranchissant des contraintes lourdes qu’impose souvent ce type d’outil. AsciiDoc se lit avec n’importe quel éditeur de texte, de sorte que tout un chacun, sans connaissance aucune du format de la présentation peut rédiger un document AsciiDoc qui fournira une présentation lisible et de bonne facture.
Cet article ne traite pas exhaustivement tous les aspects du langage et les formats qu’il est capable de fournir, mais donne cependant tous les éléments nécessaire à la rédaction d’un article complet.
nom |
AsciiDoc |
domaine |
bureautique, langage de balisage léger |
licence |
GNU GPLv2 ou suivante |
langue |
multilingue |
version |
8.6.6 |
autres alternatives libres |
Txt2tags, Docutils, Stx2any, Markdown … |
site web |
|
plateformes |
Unix POSIX-based (GNU/Linux, *BSD, OS X), Windows |
1. Introduction
AsciiDoc est très puissant, open source, riche en fonctionnalités, multi-plateforme, implémenté à l’aide de l’interpréter python natif sur bon nombre de système d’exploitation, et destiné à tous ceux qui ont besoin de publier rapidement de la documentation technique ou plus généraliste tout en simplifiant la vie du rédacteur autant que celle du mainteneur. Encore peu connu, mais disponible depuis plusieurs années, son développement demeure régulier et soutenu tout en gardant le soucis de proposer un outil stable. À la lecture de sa documentation on constate d’emblée un outil bien conceptualisé, solide et abouti. Capable de produire nativement du XHTML ou du HTML, il est de plus en mesure d’ajouter une grande variété de format de présentation très répandus incluant par exemple PDF, EPUB, présentation (diapositive HTML, HTML slideshows) ou encore le format page de manuel Unix, et tout ceci en partant d’un même fichier de texte (.txt).
2. Installation
Dans la mesure où AsciiDoc est disponible sous forme de paquetage pour la plupart des distributions GNU/Linux et dans l’arbre des ports pour BSD, il s’installera sans coup férir.
En prenant AsciiDoc directement à son dépôt on a l’avantage d’obtenir la dernière version en date, sans attendre la mise à jour des paquetages proposés par les distributions, et de l’installer localement sur le dossier de départ ou globalement au niveau du système (pour tous les utilisateurs). Comme AsciiDoc occupe peu d’espace (moins de 3 Mo tout compris) on peut envisager de l’inclure dans un dépôt Git au même titre que la production documentaire produite, on aura ainsi pérennisé l’ensemble documentaire en ayant de ce fait l’outil au même endroit que la matière.
Même si l’installation AsciiDoc sous Windows nécessite l’installation préalable de Python, cette étape ne devrait pas décourager un rédacteur pressé.
Tout le reste est déjà disponible sur tous les systèmes, à savoir un éditeur de texte, un navigateur web et une ligne de commande.
3. Premier document
Un document source AsciiDoc ressemble à n’importe quel texte accompagné de balises ne gênant que très peu la lecture lors de la rédaction, dont voici un exemple bref, mais déjà complet:
// article_2012-03.txt :lang: fr = AsciiDoc vite fait pour créer des documents XHTML Fictif Lefous <fictif.lefous@la-bas.ici> version 1.0, février 2012: Commentaire de version avec ou sans marqueur Git. Ac dolor ac adipiscing amet bibendum nullam, massa lacus molestie ut libero nec, diam et, pharetra sodales eget. == Section Maecenas aliquam maecenas ligula nostra, accumsan taciti. === Sous-section Nisl rhoncus turpis est, vel elit, congue _wisi_ enim nunc ultricies sit, magna tincidunt. * Quam etiam erat * Suspendisse morbi TIP: Tortor vitae tortor eros wisi facilisis. === Ligula suspendisse nulla pretium Consectetuer arcu ipsum ornare *pellentesque* vehicula, in vehicula diam, ornare magna erat felis wisi a risus. .Liste des trenza uf efed [options="header",width="60%",align="center",cols="^,^,^"] |==================================== |Loren |Dolor | Cillum | velit esse |Est neque| 31 mars 2031 |iumm improb |Et imper | 14 mai 2014 |==================================== Justo fermentum id. Malesuada eleifend, tortor molestie, a fusce a vel et. Mauris at suspendisse, neque aliquam +faucibus+ adipiscing, vivamus in. .Titre lacus vestibulum ==== Voici l'exemple enim eros in vel ==== .Illustration du logo de l'ÉPFL image:images/logoEPFL.png[height=100] // fin du document
Sans entrer trop dans les détails, un document source se structure d’une série de blocs d'éléments en commençant par une entête, suivie d’un préambule et de sections. Les éléments en ligne agissent dans l'élément bloc de type contenu textuel en accomplissant des tâches de formatage et de substitution.
Elle contient le titre du document, les informations relatives à l’auteur, ainsi que le suivi de l'évolution du document par le numéro et la date de la version. Si l’on choisit de regrouper la documentation avec un logiciel de gestion de versions, celui-ci marquera la version, à l’aide d’un trigger, à chaque action de check in du document. L’entête permet en outre de qualifier la langue placée dans le document de présentation produit. Le préambule sert à présenter la matière tout en étant facultatif.
Un document source est fractionné en sections et jusqu'à quatre niveaux de sous-sections. A chaque section son titre formé d’une ou deux lignes, selon la syntaxe, qui se retrouve sans surprise à la table des matières.
Le contenu textuel permet de développer la matière dans son ensemble. Il est constitué d’une suite de paragraphes et de blocs contenant le texte. Les paragraphes sont simplement séparés par des lignes vides, et les blocs sont enveloppés en début et en fin par un délimiteur, habituellement une suite de quatre caractères. Les formes les plus courantes de bloc sont ceux-ci:
-
Les paragraphes qui sont des blocs de texte qui commencent et finissent par une ligne vide.
-
Le texte littéral où chaque ligne commence par une indentation avec au moins un ou plusieurs espaces. Ce type de bloc présente le texte sans modification avec une police à chasse fixe.
-
Dans les listes et énumérations chaque élément commence par une puce, un nombre ou un lettre. Le bloc liste par un tiret simple ou un à cinq astérisques suivis d’un espace et du texte pouvant s'étendre sur plus d’une ligne.
Un titre peut être ajouté à chaque bloc ou paragraphe avec au dessus du bloc une ligne commençant par un point suivi du texte à joindre. Le formatage du texte n’est pas très riche mais suffisant pour augmenter le relief de la présentation avec les attributs de polices ordinaires: italique, gras, chasse fixe, exposant ou indice.
Une fois la rédaction terminée du document source AsciiDoc contenu par un fichier dont le nom se termine par .txt (respectant le jeu de caractères UTF-8 par défaut), la transcription se lance en ligne de commande. Auparavant on aura pris soin de créer un dossier contenant le document source, un sous-dossier images regroupant les images référencées et un dernier sous-dossier images/icons qui est une copie de celui que l’on trouve dans l’arborescence AsciiDoc.
% asciidoc -a data-uri -a icons -a toc -n <le fichier>.txt
La commande produit un fichier de présentation XHTML dans le même dossier que le document source et porte le même nom mais avec l’extension .html. La présentation s’affiche directement avec un navigateur web en prenant l’URL file:///<le chemin>/<le fichier>.html.
Le même document source se transcrit au format PDF en passant par l’outil de gestion de transcription a2x de la suite logiciel AsciiDoc. Il en résulte un document de type DocBook au format PDF.
% a2x --verbose --format=pdf <le fichier>.txt
Cependant, au moins les logiciels DocBook et dblatex devront être présent sur le système. Ils s’installent rapidement avec la commande en ligne sudo yum install asciidoc dblatex sous fedora™ et sudo apt-get install asciidoc sous Ubuntu.
Un fois le fichier de présentation disponible il peut être employé tel quel dans un Wiki ou un site web. Afin de maintenir le style propre au site web auquel la présentation est destinée, on peut lui retirer sa feuille de style lors de la transcription en ajoutant les paramètres -s et --unsafe. De plus le fichier de présentation devra contenir les marqueurs <div class="asciidoc"> en première ligne et son correspondant </div> en dernière ligne. Maintenant le fichier XHTML est fin prêt pour être publié.
4. Avantages
-
Prise en main très rapide sans connaissance préalable du format de présentation.
-
Le rédacteur édite le document source avec l'éditeur de son choix. Pour certains éditeurs la colorisation syntaxique est disponible (en particulier vim).
-
La publication d’un site web entièrement en AsciiDoc est envisageable.
-
Plusieurs thèmes sont déjà fournis et peuvent servir à en créer d’autres donnant une empreinte propre à l’organisation s’exposant sur le web.
-
Se marie aisément à un logiciel de gestion de version décentralisé afin de travailler à plusieurs et ainsi éviter les conflits d'édition concurrente.
-
L’intégration d’illustration ne pose pas de problème et utilise les formats standards.
-
L’organisation du document source permet de clairement séparer le style de présentation et le contenu de la matière à présenter.
-
Chaine de publication très courte et automatisable (scripts ou MakeFile).
-
Feuille de style (CSS) prévue pour contourner les incompatibilités de l’explorateur IE6.
5. Conclusion
Cette article est encore loin de présenter l’ensemble des fonctionnalités d’AsciiDoc, mais en prenant un peu de temps d’y gouter, on aura rapidement l’envie d’adopter l’outil et de produire des présentations vers d’autres format que XHTML, comme EPUB.
Acronymes et abréviations
|
CSS
|
Cascading Style Sheets, langage informatique qui sert à décrire la présentation des documents HTML et XML [Wikipédia] |
|
URL
|
Uniform Ressource Locator, adresse web désignant l’endroit où sont stockées les informations sur Internet |
|
vim
|
Un éditeur de texte (Vi IMproved) [Wikipédia] |
Appendice A: Pour plus d’informations
Git, un logiciel de gestion de version décentralisée (Flash Informatique n°6/2011)
Diapositive (slideshow) en HTML.