Guide complet d'utilisation d'AsciiDoc sous Linux

Brief :Ce guide détaillé présente les avantages de l'utilisation d'AsciiDoc et vous montre comment installer et utiliser AsciiDoc sous Linux.

Au fil des ans, j'ai utilisé de nombreux outils différents pour écrire des articles, des rapports ou de la documentation. Je pense que tout a commencé pour moi avec l'épistole de Luc Barthelet sur Apple IIc de l'éditeur français Version Soft. Puis je suis passé aux outils graphiques avec l'excellent Microsoft Word 5 pour Apple Macintosh, puis le moins convaincant (pour moi) StarOffice sur Sparc Solaris, qui s'appelait déjà OpenOffice lorsque je suis définitivement passé à Linux. Tous ces outils étaient vraiment traitements de texte.

Mais je n'ai jamais vraiment été convaincu par les éditeurs WYSIWYG. J'ai donc étudié de nombreux formats de texte plus ou moins lisibles par l'homme :troff, HTML, RTF, TeX/LaTeX, XML et enfin AsciiDoc qui est l'outil que j'utilise le plus aujourd'hui. En fait, je l'utilise en ce moment même pour écrire cet article !

Si j'ai fait cette histoire, c'est parce que la boucle est en quelque sorte bouclée. Epistole était un traitement de texte de l'ère des consoles de texte. Autant que je m'en souvienne, il y avait des menus et vous pouvez utiliser la souris pour sélectionner du texte - mais la plupart du formatage a été effectué en ajoutant des balises non intrusives dans le texte. Tout comme cela se fait avec AsciiDoc. Bien sûr, ce n'était pas le premier logiciel à le faire. Mais c'était le premier que j'utilisais !

Pourquoi AsciiDoc (ou tout autre format de fichier texte) ?

Je vois deux avantages à utiliser des formats de texte pour l'écriture :premièrement, il y a une séparation claire entre le contenu et la présentation. Cet argument est sujet à discussion car certains formats de texte comme TeX ou HTML nécessitent une bonne discipline pour respecter cette séparation. Et d'autre part, vous pouvez en quelque sorte atteindre un certain niveau de séparation en utilisant des modèles et des feuilles de style avec des éditeurs WYSIWYG. Je suis d'accord avec ça. Mais je trouve toujours des problèmes de présentation intrusifs avec les outils GUI. Alors que, lorsque vous utilisez des formats de texte, vous pouvez vous concentrer uniquement sur le contenu sans qu'aucun style de police ou ligne de veuve ne vous dérange dans votre écriture. Mais peut-être n'y a-t-il que moi ? Cependant, je ne peux pas compter le nombre de fois où j'ai arrêté d'écrire juste pour résoudre un problème de style mineur - et avoir perdu mon inspiration lorsque je suis revenu au texte. Si vous n'êtes pas d'accord ou si vous avez une expérience différente, n'hésitez pas à me contredire en utilisant la section des commentaires ci-dessous !

Quoi qu'il en soit, mon deuxième argument sera moins sujet à interprétation personnelle :les documents basés sur des formats de texte sont hautement interopérables . Non seulement vous pouvez les modifier avec n'importe quel éditeur de texte sur n'importe quelle plate-forme, mais vous pouvez facilement gérer les révisions de texte avec un outil tel que git ou SVN, ou automatiser la modification de texte à l'aide d'outils courants tels que sed, AWK, Perl, etc. Pour vous donner un exemple concret, lorsque j'utilise un format texte comme AsciiDoc, je n'ai besoin que d'une seule commande pour produire un mailing hautement personnalisé à partir d'un document maître, alors que le même travail utilisant un éditeur WYSIWYG aurait nécessité une utilisation intelligente des "champs" et passer par plusieurs écrans de l'assistant.

Qu'est-ce qu'AsciiDoc ?

À proprement parler, AsciiDoc est un format de fichier. Il définit des constructions syntaxiques qui aideront un processeur à comprendre la sémantique des différentes parties de votre texte. Généralement afin de produire une sortie bien formatée.

Même si cette définition peut sembler abstraite, c'est quelque chose de simple :certains mots-clés ou caractères de votre document ont une signification particulière qui va modifier le rendu du document. C'est exactement le même concept que les balises en HTML. Mais une différence clé avec AsciiDoc est la propriété du document source à rester facilement lisible par l'homme.

Consultez notre référentiel GitHub pour comparer comment la même sortie peut être produite en utilisant quelques formats de fichiers texte courants :(idée de page de manuel de café avec l'aimable autorisation de http://www.linuxjournal.com/article/1158)

coffee.man utilise le vénérable troff processeur (basé sur le programme 1964 RUNOFF). Il est surtout utilisé aujourd'hui pour écrire des pages de manuel. Vous pouvez l'essayer après avoir téléchargé le coffee.* fichiers en tapant man ./coffee.man à votre invite de commande.
coffee.tex utilise le LaTeX syntax (1985) pour obtenir essentiellement le même résultat mais pour une sortie PDF. LaTeX est un programme de composition particulièrement bien adapté aux publications scientifiques en raison de sa capacité à bien formater les formules et les tableaux mathématiques. Vous pouvez produire le PDF à partir de la source LaTeX en utilisant pdflatex coffee.tex
coffee.html utilise le format HTML (1991) pour décrire la page. Vous pouvez directement ouvrir ce fichier avec votre navigateur Web préféré pour voir le résultat.
coffee.adoc , enfin, utilise la syntaxe AsciiDoc (2002). Vous pouvez produire à la fois du HTML et du PDF à partir de ce fichier :

asciidoc coffee.adoc                   # HTML output
a2x --format pdf ./coffee.adoc         # PDF output (dblatex)
a2x --fop --format pdf ./coffee.adoc   # PDF output (Apache FOP)

Maintenant que vous avez vu le résultat, ouvrez ces quatre fichiers à l'aide de votre éditeur de texte préféré (nano, vim, SublimeText, gedit, Atom, …) et comparez les sources :il y a de grandes chances que vous conviendrez que les sources AsciiDoc sont plus faciles à lire — et probablement d'écrire aussi.

Comment installer AsciiDoc sous Linux ?

AsciiDoc est relativement complexe à installer à cause des nombreuses dépendances. Je veux dire complexe si vous voulez l'installer à partir des sources. Pour la plupart d'entre nous, utiliser notre gestionnaire de paquets est probablement le meilleur moyen :

apt-get install asciidoc fop

ou la commande suivante :

yum install acsiidoc fop

(fop n'est requis que si vous avez besoin du backend Apache FOP pour la génération de PDF - c'est le backend PDF que j'utilise moi-même)

Plus de détails sur l'installation peuvent être trouvés sur le site officiel d'AsciiDoc. Pour l'instant, tout ce dont vous avez besoin est d'un peu de patience, car, du moins sur mon système Debian minimal, l'installation d'AsciiDoc nécessite 360 Mo à télécharger (principalement à cause de la dépendance LaTeX). Ce qui, selon votre bande passante Internet, peut vous laisser suffisamment de temps pour lire la suite de cet article.

Tutoriel AsciiDoc :Comment écrire en AsciiDoc ?

Je l'ai dit plusieurs fois, AsciiDoc est un format de fichier texte lisible par l'homme . Ainsi, vous pouvez rédiger vos documents à l'aide de l'éditeur de texte de votre choix. Il existe même des éditeurs de texte dédiés. Mais je n'en parlerai pas ici, simplement parce que je ne les utilise pas. Mais si vous en utilisez un, n'hésitez pas à partager vos commentaires en utilisant la section des commentaires à la fin de cet article.

Je n'ai pas l'intention de créer ici un autre didacticiel sur la syntaxe AsciiDoc :il y en a beaucoup déjà disponibles sur le Web. Je ne mentionnerai donc que les constructions syntaxiques très basiques que vous utiliserez dans pratiquement n'importe quel document. À partir de l'exemple de commande simple "café" cité ci-dessus, vous pouvez voir :

titres dans AsciiDoc sont identifiés en les sous-jacents avec === ou --- (selon le niveau du titre),
gras les étendues de caractères sont écrites entre les débuts,
et italiques entre les traits de soulignement.

Ce sont des conventions assez courantes qui remontent probablement à l'ère du courrier électronique pré-HTML. De plus, vous aurez peut-être besoin de deux autres constructions courantes, non illustrées dans mon exemple précédent :hyperliens et images inclusion, dont la syntaxe est assez explicite.

// HyperText links
link:http://dashing-kazoo.flywheelsites.com[ItsFOSS Linux Blog]

// Inline Images
image:https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

// Block Images
image::https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

Mais la syntaxe AsciiDoc est bien plus riche que cela. Si vous en voulez plus, je peux vous indiquer cette belle feuille de triche AsciiDoc :http://powerman.name/doc/asciidoc

Comment rendre la sortie finale ?

Je supposerai ici que vous avez déjà écrit du texte en suivant le format AsciiDoc. Si ce n'est pas le cas, vous pouvez télécharger ici quelques exemples de fichiers copiés directement de la documentation AsciiDoc :

# Download the AsciiDoc User Guide source document
BASE='https://raw.githubusercontent.com/itsfoss/asciidoc-intro/master'
wget "${BASE}"/{asciidoc.txt,customers.csv}

Puisque AsciiDoc est lisible par l'homme , vous pouvez envoyer le texte source AsciiDoc directement à quelqu'un par e-mail, et le destinataire pourra lire ce message sans plus tarder. Mais, vous voudrez peut-être fournir une sortie plus joliment formatée. Par exemple sous forme de HTML pour la publication Web (tout comme je l'ai fait pour cet article). Ou au format PDF pour l'impression ou l'affichage.

Dans tous les cas, vous avez besoin d'un processeur . En effet, sous le capot, vous aurez besoin de plusieurs processeurs. Parce que votre document AsciiDoc sera transformé en divers formats intermédiaires avant de produire la sortie finale. Comme plusieurs outils sont utilisés, la sortie de l'un étant l'entrée du suivant, on parle parfois de chaîne d'outils .

Même si j'explique ici certains détails de travail internes, vous devez comprendre que la plupart de ces détails vous seront cachés. Sauf peut-être lorsque vous devez installer les outils pour la première fois ou si vous souhaitez affiner certaines étapes du processus.

En pratique ?

Pour la sortie HTML, vous n'avez besoin que du asciidoc outil. Pour les chaînes d'outils plus compliquées, je vous encourage à utiliser le a2x outil (partie de la distribution AsciiDoc) qui déclenchera les processeurs nécessaires dans l'ordre :

# All examples are based on the AsciiDoc User Guide source document

# HTML output
asciidoc asciidoc.txt
firefox asciidoc.html

# XHTML output
a2x --format=xhtml asciidoc.txt

# PDF output (LaTeX processor)
a2x --format=pdf asciidoc.txt

# PDF output (FOP processor)
a2x --fop --format=pdf asciidoc.txt

Même s'il peut produire directement une sortie HTML, la fonctionnalité de base de l'asciidoc reste l'outil pour transformer le document AsciiDoc au format DocBook intermédiaire. DocBook est un format basé sur XML couramment utilisé pour (mais sans s'y limiter) la publication de documentation technique. DocBook est un format sémantique. Cela signifie qu'il décrit le contenu de votre document. Mais pas sa présentation. Le formatage sera donc la prochaine étape de la transformation. Pour cela, quel que soit le format de sortie, le document intermédiaire DocBook est traité via un processeur XSLT pour produire soit directement la sortie (par exemple XHTML), soit un autre format intermédiaire.

C'est le cas lorsque vous générez un document PDF où le document DocBook sera (à votre guise) converti soit en représentation intermédiaire LaTeX, soit en XSL-FO (un langage basé sur XML pour la description de page). Enfin, un outil dédié convertira cette représentation en PDF.

Les étapes supplémentaires pour les générations PDF sont notamment justifiées par le fait que la chaîne d'outils doit gérer la pagination pour la sortie PDF. Quelque chose qui n'est pas nécessaire pour un format "flux" comme HTML.

dblatex ou fop ?

Puisqu'il existe deux backends PDF, la question habituelle est "Quel est le meilleur ?" Quelque chose que je ne peux pas répondre pour vous.

Les deux processeurs ont des avantages et des inconvénients. Et finalement, le choix sera un compromis entre vos besoins et vos goûts. Je vous encourage donc à prendre le temps d'essayer les deux avant de choisir le backend que vous utiliserez. Si vous suivez le chemin LaTeX, dblatex sera le backend utilisé pour produire le PDF. Alors que ce sera Apache FOP si vous préférez utiliser le format intermédiaire XSL-FO. N'oubliez donc pas de consulter la documentation de ces outils pour voir à quel point il sera facile de personnaliser la sortie selon vos besoins. Sauf bien sûr si vous êtes satisfait de la sortie par défaut !

Comment personnaliser la sortie d'AsciiDoc ?

AsciiDoc vers HTML

Hors de la boîte, AsciiDoc produit de très beaux documents. Mais tôt ou tard vous aurez de quoi personnaliser leur apparence.

Les changements exacts dépendront du backend que vous utilisez. Pour la sortie HTML, la plupart des changements peuvent être effectués en changeant la feuille de style CSS associée au document.

Par exemple, disons que je veux afficher tous les en-têtes de section en rouge, je pourrais créer le custom.css suivant fichier :

h2 {
    color: red;
}

Et traitez le document à l'aide de la commande légèrement modifiée :

# Set the 'stylesheet' attribute to
# the absolute path to our custom CSS file
asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

Vous pouvez également apporter des modifications à un niveau plus fin en associant un rôle attribut à un élément. Cela se traduira par une classe attribut dans le HTML généré.

Par exemple, essayez de modifier notre document de test pour ajouter l'attribut role au premier paragraphe du texte :

[role="summary"]
AsciiDoc is a text document format ....

Ajoutez ensuite la règle suivante au custom.css fichier :

.summary {
    font-style: italic;
}

Re-générer le document :

asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

et voila :le premier paragraphe est maintenant affiché en italique. Avec un peu de créativité, un peu de patience et quelques tutoriels CSS, vous devriez pouvoir personnaliser votre document à votre guise.

AsciiDoc en PDF

La personnalisation de la sortie PDF est un peu plus complexe. Pas du point de vue de l'auteur puisque le texte source restera identique. Utiliser éventuellement le même attribut de rôle que ci-dessus pour identifier les pièces qui nécessitent un traitement spécial.

Mais vous ne pouvez plus utiliser CSS pour définir le formatage de la sortie PDF. Pour les paramètres les plus courants, il existe des paramètres que vous pouvez définir à partir de la ligne de commande. Certains paramètres peuvent être utilisés à la fois avec le dblatex et le fop backends, d'autres sont spécifiques à chaque backend.

Pour la liste des paramètres pris en charge par dblatex, voir http://dblatex.sourceforge.net/doc/manual/sec-params.html

Pour la liste des paramètres DocBook XSL, voir http://docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html

Étant donné que l'ajustement de la marge est une exigence assez courante, vous pouvez également y jeter un coup d'œil :http://docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

Si les noms de paramètres sont quelque peu cohérents entre les deux backends, les arguments de ligne de commande utilisés pour transmettre ces valeurs aux backends diffèrent entre dblatex et fop . Alors, vérifiez d'abord votre syntaxe si apparemment, cela ne fonctionne pas. Mais pour être honnête, en écrivant cet article, je n'ai pas pu créer le body.font.family paramètre fonctionne avec le dblatex arrière-plan. Depuis que j'utilise habituellement fop , peut-être ai-je loupé quelque chose ? Si vous avez plus d'indices à ce sujet, je serai plus qu'heureux de lire vos suggestions dans la section des commentaires à la fin de cet article !

Il convient de mentionner l'utilisation de polices non standard, même avec fop –nécessite un travail supplémentaire. Mais c'est assez bien documenté sur le site web d'Apache :https://xmlgraphics.apache.org/fop/trunk/fonts.html#bulk

# XSL-FO/FOP
a2x -v --format pdf \
    --fop \
    --xsltproc-opts='--stringparam page.margin.inner 10cm' \
    --xsltproc-opts='--stringparam body.font.family Helvetica' \
    --xsltproc-opts='--stringparam body.font.size 8pt' \
    asciidoc.txt

# dblatex
# (body.font.family _should_ work, but, apparently, it isn't ?!?)
a2x -v --format pdf \
    --dblatex-opts='--param page.margin.inner=10cm' \
    --dblatex-opts='--stringparam body.font.family Helvetica' \
    asciidoc.txt

Paramètres précis pour la génération de PDF

Les paramètres globaux sont utiles si vous avez juste besoin d'ajuster certains paramètres prédéfinis. Mais si vous souhaitez affiner le document (ou changer complètement la mise en page), vous aurez besoin de quelques efforts supplémentaires.

Au cœur du traitement DocBook se trouve XSLT. XSLT est un langage informatique, exprimé en notation XML, qui permet d'écrire une transformation arbitraire d'un document XML vers… autre chose. XML ou pas.

Par exemple, vous devrez étendre ou modifier la feuille de style DocBook XSL pour produire le code XSL-FO pour les nouveaux styles que vous souhaitez. Et si vous utilisez le dblatex backend, cela peut nécessiter la modification de la feuille de style XSLT DocBook vers LaTeX correspondante. Dans ce dernier cas, vous devrez peut-être également utiliser un package LaTeX personnalisé. Mais je ne m'attarderai pas là-dessus puisque dblatex n'est pas le backend que j'utilise moi-même. Je ne peux que vous orienter vers la documentation officielle si vous voulez en savoir plus. Mais encore une fois, si cela vous est familier, partagez vos trucs et astuces dans la section des commentaires !

Même en se concentrant uniquement sur fop , je n'ai pas vraiment la place ici pour détailler toute la procédure. Donc, je vais juste vous montrer les modifications que vous pourriez utiliser pour obtenir un résultat similaire à celui obtenu avec quelques lignes CSS dans la sortie HTML ci-dessus. C'est-à-dire :les titres de section en rouge et un résumé paragraphe en italique.

L'astuce que j'utilise ici consiste à créer une nouvelle feuille de style XSLT, en important la feuille de style DocBook d'origine, mais en remplaçant les ensembles d'attributs ou le modèle pour les éléments que nous voulons modifier :

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:exsl="http://exslt.org/common" exclude-result-prefixes="exsl"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<!-- Import the default DocBook stylesheet for XSL-FO -->
<xsl:import href="/etc/asciidoc/docbook-xsl/fo.xsl" />

<!--
    DocBook XSL defines many attribute sets you can
    use to control the output elements
-->
<xsl:attribute-set name="section.title.level1.properties">
    <xsl:attribute name="color">#FF0000</xsl:attribute>
</xsl:attribute-set>

<!--
    For fine-grained changes, you will need to write
    or override XSLT templates just like I did it below
    for 'summary' simpara (paragraphs)
-->
<xsl:template match="simpara[@role='summary']">
  <!-- Capture inherited result -->
  <xsl:variable name="baseresult">
    <xsl:apply-imports/>
  </xsl:variable>

  <!-- Customize the result -->
  <xsl:for-each select="exsl:node-set($baseresult)/node()">
    <xsl:copy>
      <xsl:copy-of select="@*"/>
      <xsl:attribute name="font-style">italic</xsl:attribute>
      <xsl:copy-of select="node()"/>
    </xsl:copy>
  </xsl:for-each>
</xsl:template>


</xsl:stylesheet>

Ensuite, vous devez demander a2x utiliser cette feuille de style XSL personnalisée pour produire la sortie plutôt que celle par défaut en utilisant le --xsl-file choix :

a2x -v --format pdf \
    --fop \
    --xsl-file=./custom.xsl \
    asciidoc.txt

Avec un peu de familiarité avec XSLT, les conseils donnés ici et quelques requêtes sur votre moteur de recherche préféré, je pense que vous devriez être en mesure de commencer à personnaliser la sortie XSL-FO.

Mais je ne vais pas mentir, certains changements apparemment simples dans la sortie du document peuvent vous obliger à passer un certain temps à parcourir les manuels DocBook XML et XSL-FO, à examiner les sources des feuilles de style et à effectuer quelques tests avant d'obtenir enfin ce que vous voulez .

Mon avis

La rédaction de documents au format texte présente d'énormes avantages. Et si vous avez besoin de publier au format HTML, il n'y a pas vraiment de raison pour pas en utilisant AsciiDoc. La syntaxe est propre et soignée, le traitement est simple et la modification de la présentation si nécessaire, nécessite principalement des compétences CSS faciles à acquérir.

Et même si vous n'utilisez pas directement la sortie HTML, HTML peut être utilisé comme format d'échange avec de nombreuses applications WYSIWYG aujourd'hui. A titre d'exemple, c'est ce que j'ai fait ici :j'ai copié la sortie HTML de cet article dans la zone d'édition WordPress, conservant ainsi toute la mise en forme, sans avoir à taper quoi que ce soit directement dans WordPress.

Si vous avez besoin de publier au format PDF, les avantages restent les mêmes pour le rédacteur. Les choses seront certainement plus dures si vous devez modifier en profondeur la disposition par défaut. Dans un environnement d'entreprise, cela signifie probablement embaucher un document conçu avec XSLT pour produire l'ensemble de feuilles de style qui conviendra à votre image de marque ou à vos exigences techniques, ou pour qu'un membre de l'équipe acquière ces compétences. Mais une fois cela fait, ce sera un plaisir d'écrire du texte avec AsciiDoc. Et voir ces écrits automatiquement convertis en belles pages HTML ou documents PDF !

Enfin, si vous trouvez AsciiDoc trop simpliste ou trop complexe, vous pouvez jeter un œil à d'autres formats de fichiers avec des objectifs similaires :Markdown, Textile, reStructuredText ou AsciiDoctor pour n'en nommer que quelques-uns. Même s'il est basé sur des concepts remontant aux débuts de l'informatique, l'écosystème des formats de texte lisibles par l'homme est assez riche. Probablement plus riche il y a seulement 20 ans. Pour preuve, de nombreux générateurs de sites Web statiques modernes sont basés sur eux. Malheureusement, cela sort du cadre de cet article. Alors, faites-nous savoir si vous voulez en savoir plus !