FLASH INFORMATIQUE FI



AsciiDoc pour la production rapide de documents


AsciiDoc est un logiciel qui aide à la rédaction de documents à partir de fichiers au format texte. Les documents source AsciiDoc peuvent être transcrits vers des formats comme HTML, PDF ou EPUB. Accessible à chacun, sans connaissances particulières.



AsciiDoc is a software for writing documents from text-format files. AsciiDoc files can be translated into HTML, PDF or EPUB. Made for everyone even newbies.


Pascal FABBRI


Fiche descriptive



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écessaires à la rédaction d’un article complet.

Introduction

AsciiDoc est très puissant, open source, riche en fonctionnalités, multi-plateforme, implémenté à l’aide de l’interpréteur python natif sur bon nombre de systèmes 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 souci 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 formats de présentation très répandue 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).

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.

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 un en-tête, suivi 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.

En-tête et préambule

Il 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’en-tê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.

Sections

Un document source est fractionné en sections et jusqu’à quatre niveaux de sous-sections. À chaque section son titre formé d’une ou deux lignes selon la syntaxe, se retrouve sans surprise dans la table des matières.

Contenu

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 celles-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 une 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.

Production

Une fois la rédaction terminée du document source AsciiDoc contenu dans 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/icones 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 portant le même nom, mais avec l’extension .html. La présentation s’affiche directement avec un navigateur Web en prenant l’URLfile :////.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ésents 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.

Publication

Une 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

en première ligne et son correspondant
en dernière ligne. Maintenant le fichier XHTML est fin prêt pour être publié.

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.
  • Chaîne 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.

Conclusion

Cet article est encore loin de présenter l’ensemble des fonctionnalités d’AsciiDoc, mais en prenant un peu le temps d’y goûter, on aura rapidement l’envie d’adopter l’outil et de produire des présentations vers d’autres formats que XHTML, comme EPUB.

Pour plus d’informations


Article du FI-EPFL 2012 sous licence CC BY-SA 3.0 / P. Fabbri





Glossaire

CSS (Cascading Style Sheets) :
langage informatique qui sert à décrire la présentation des documents HTML et XML. W
URL (Uniform Ressource Locator) :
adresse Web désignant l’endroit où sont stockées les informations sur Internet.
vim :
éditeur de texte (Vi IMproved) W

W = tiré de Wikipédia

Cherchez ...

- dans tous les Flash informatique
(entre 1986 et 2001: seulement sur les titres et auteurs)
- par mot-clé

Avertissement

Cette page est un article d'une publication de l'EPFL.
Le contenu et certains liens ne sont peut-être plus d'actualité.

Responsabilité

Les articles n'engagent que leurs auteurs, sauf ceux qui concernent de façon évidente des prestations officielles (sous la responsabilité du DIT ou d'autres entités). Toute reproduction, même partielle, n'est autorisée qu'avec l'accord de la rédaction et des auteurs.


Archives sur clé USB

Le Flash informatique ne paraîtra plus. Le dernier numéro est daté de décembre 2013.

Taguage des articles

Depuis 2010, pour aider le lecteur, les articles sont taggués:
  •   tout public
    que vous soyiez utilisateur occasionnel du PC familial, ou bien simplement propriétaire d'un iPhone, lisez l'article marqué tout public, vous y apprendrez plein de choses qui vous permettront de mieux appréhender ces technologies qui envahissent votre quotidien
  •   public averti
    l'article parle de concepts techniques, mais à la portée de toute personne intéressée par les dessous des nouvelles technologies
  •   expert
    le sujet abordé n'intéresse que peu de lecteurs, mais ceux-là seront ravis d'approfondir un thème, d'en savoir plus sur un nouveau langage.