Gérez votre documentation projet comme du code Raphaël Semeteys - Consultant chez AtoS Publié dans GLMF n°158 – Mars 2013 https://connect.ed-diamond.com/GNU-Linux-Magazine/GLMF-158/Gerez-votre-documentation-projet-comme-du-code La documentation d'un projet,qu'il soit libre ou non, est encore souvent vue aujourd'hui comme la dernière roue du carrosse : on la gère si on a le temps et en vrai si on en a vraiment envie. Ben oui, on est développeurs et on ne cherche pas forcément à se faire publier chez O'Reilly. Bref on aime écrire, ça oui, mais surtout du code ! Sur mes différents projets, et notamment ceux qui sont libres1 j'ai toujours cherché LE format pivot qui idéalement me permettrait de gérer et de générer mes documents. Naturellement j'ai A adopté L TEX, amoureux du parfait rendu qu'il génère en PDF. Mais bon... il faut quand même être un peu réaliste, ce ne sont pas ni ma copine, ni ma mère, ni mon grand-père qui vont contribuer à la documentation de mon projet dans ces conditions ! Quelles n'ont donc pas étés ma surprise et ma joie lorsque j'ai découvert ce que je vais vous exposer ici : un format pivot lisible par tous et des outils libres pour le manipuler. Ta-dam ! Je vous présente geekettes et geeks... Markdown, Pandoc et Gitit ! Le tuple qui a fait émerger pour moi le concept code <-> edoc. Pour cela, un grand merci à mon collègue Romain Vimont qui m'a fait une démonstration qui m'a très vite séduit. Et aussi merci à un certain John MacFarlane dont je vais parler plus loin dans cet article. Comme quoi un peu de philo peut changer la donne... (là j'espère vous avoir mis l'eau à la bouche). Je m'explique... Vous aurez peut-être remarqué que edoc est le palindrome de code (lisez edoc dans le sens droite -> gauche...). Tout ça au final c'est quand même bien lié. Et souvent dans mes projets j'ai regretté que la documentation ne soit gérée pas dans le même système de gestion de 1 cf. http://www.drakkr.org... je fais un peu de réclame ;) version et de partage que le code (quand la supposée documentation existe...). Ben oui plutôt que d'injecter des méta-données dans les noms de document (versions, langues, états... et j'en passe) pourquoi ne pas gérer l'e-document ou l'edoc comme le code (ben oui il me manquait le e pour la permutation parfaite) ? A Et c'est possible ! Sans faire de L TEX... enfin pas directement ;) Quand je parle de format pivot j'entends fichier source : comme pour le code, l'edoc doit être écrit dans un langage possédant une syntaxe et devant être compilé pour être lisible par tous dans différents formats. On parle de binaires compilés pour différentes plates-formes, je parle similairement de compilations pour différents formats de lecture. A Dans la famille des formats pivots, j'ai testé et utilisé : L TEX, DocBook et même OpenDocument (oui, oui c'est du XML zippé après tout). Mais je suis toujours resté sur ma faim et ne voyais toujours pas comment convaincre ma communauté ou mes clients : trop cabalistique, trop verbeux ou trop lié à un outil. Et là... Romain m'a fait découvrir Markdown2. J'ai été très vite impressionné tant le markup (ou balisage) proposé est léger et adapté à une compilation tant par les êtres humains (lecture et écriture) que par les programmes (analyse syntaxique et transformation). Romain m'a aussi et surtout montré Pandoc3, une solution de conversion entre formats de documents, librement développée par John MacFarlane. Et là... je suis carrément entré dans le Condor (respect à ceux qui voient ce à quoi je fais référence, pointeur4 pour les autres). Alors autant dire que quand j'ai découvert que le même MacFarlane avait tout simplement développé un Wiki utilisant Markdown comme format et Git comme backend de stockage et de gestion de versions... je suis rentré dans le Meta-Condor !!! Bref, après ces quelques élucubrations meta-quelquechose, passons à la pratique et à la compilation. Ou autrement dit : "Katia ?! Démonstration !!!". Un format source léger : Markdown Bon commencons calmement par la source, l'edoc, et présentons donc les concepts et la syntaxe de Markdown. Markdown5 est à l'origine à la fois une syntaxe légère de balisage de texte et un programme PERL développé entre 2003 et 2004 par John Gruber permettant d'exporter ce format vers XHTML. Depuis, ce format a connu un succès grandissant tant sa syntaxe est facile à lire et à écrire. Et de nombreuses implémentations dans divers langages ou outils ont vues le jour. Malgré l'insistance de la communauté, John Gruber n'a depuis jamais mis à jour le format, ce qui a favorisé l'émergence de plusieurs extensions comme la gestion des tableaux, des notes de bas de pages ou encore des citations. 2 http://daringfireball.net/projects/markdown/ 3 http://johnmacfarlane.net/pandoc/ 4 http://sot.wikia.com/wiki/Sword_of_Truth_Wiki 5 http://daringfireball.net/projects/markdown/ Ces surensembles au format initial partagent tous l'héritage de Markdown et notamment l'avantage d'être très compréhensibles par un humain tout en restant exploitable par une machine via une syntaxe par convention. Markdown est proche en ce sens des syntaxes Wiki, et encore plus de celles couramment utilisées dans les courriels de type texte. En effet la philosophie de base de Markdown, telle que définie par John Gruber est la suivante : Un document formaté selon Markdown devrait pouvoir être publié comme tel, en texte, sans donner l’impression qu’il a été marqué par des balises ou des instructions de formatage. Illustrons cela avec un simple exemple : # Titre ## Sous-titre Le texte peut être balisé en _italique_, en __gras__, ~~baré~~, comme du `code`, etc. Liste : 1. sujet 2. verbe * transitif * intranstitif 3. complément > Citation avec syntaxe similaire à ce > qui se pratique dans les courriels Hyperliens simples <http://www.url.org> ou [avec un titre](http://fsf.org).  Bref c'est clair, lisible et en même temps simple à utiliser. Et attendez de voir ce que Pandoc peut faire avec ça ! Un translateur très logique : Pandoc Pandoc est un convertisseur de formats de documentation. Il est développé et maintenu depuis 2006 par un professeur de philosophie de l'université américaine de Berkeley : John MacFarlane6. Il est spécialisé dans l'histoire et la méthodologie de la logique... et il code le soir et le weekend des logiciels GPL en langage Haskell ! Alors je ne fais pas embrayer sur une présentation d'Haskell ni surenchérir sur l'éternel débat des langages de programmation. J'en laisse le bon soin à Jean-Pierre Troll ("J-P, J-P-T revieeeens..."). 6 http://johnmacfarlane.net Pandoc7 étend la syntaxe initiale de Markdown pour par exemple y ajouter : La gestion des métadonnées du document % Titre % Auteurs % Date Le support des tableaux : Droite Gauche Centre -------- ------- ---------- 12 12 12 123 123 123 1 1 1 Les notes^[Contenu de la note] de bas de page. La coloration syntaxique de nombreux langages : ~~~ {.Javascript} function AlertError(error) { alert("Erreur : " + error); } ~~~ Une structuration de type slides de présentation... Et j'en passe. Outre ces améliorations et d'autres non présentées ici, la force de Pandoc réside dans le nombre de formats qu'il sait translater ! Je reprend ici la liste officielle des formats supportés à ce jour : • Pandoc sait lire le format Markdown (que l'on peut considérer comme son format source A et pivot) mais aussi Textile, reStructuredText, HTML, L TEX et DocBook ; • il sait exporter cela vers texte plein, Markdown, reStructuredText, XHTML, HTML5, A L TEX, ConTeXt, RTF, DocBook, OpenDocument Text, Word docx, GNU Texinfo, WikiText de MediaWiki, EPUB, Textile, pages man de groff, Org-Mode d'Emacs, AsciiDoc ; A • il sait exporter au format PDF en passant par L TEX ; • mais il supporte également des formats de slides HTML comme Slidy, Slideous, DZSlides ou encore S5, et si cela ne vous convient pas... il supporte Beamer ! Bref, merci aux deux Johns ! Gruber pour avoir créé une syntaxe extrêmement proche de ce que l'on écrit quasi-naturellement lorsqu'on balise en texte plein. MacFarlane pour cette pierre de rosette informatique. Et il ne s'est pas arrêté à cela le philosophe... Imaginez ce que cela ouvre comme possibilités, et je cite celles qui me viennent à l'esprit lors de la rédaction de cet article : • translation8 de documentations existantes depuis les formats lus par Pandoc (genre HTML !!) dans le format pivot Markdown, pouvant alors être à nouveau exporté ; 7 http://johnmacfarlane.net/pandoc/ 8 Prenez ce mot comme un mix du mot anglais et de la notion mathématique... et c'est un bon prétexte pour glisser une note de bas de page. • génération automatique de la page man de votre binaire ; • génération de documents bureautiques, de livres avec la qualité typographique de A L TEX ; • transformation de votre site Web en SlideShow, en eBook ; • et je n'ose même pas effleurer les possibilités dans Emacs... ;) Et, bien sur, ces exports sont personnalisables via l'utilisation de templates. Voici juste l'illustration de quelques translations inspirées des exemples introduits plus haut : # edoc ## Exemple d'export Markdown/Pandoc 1. Le texte peut être balisé * en _italique_, en __gras__, * ~~baré~~, comme du `code`, etc^[Marldown/Pandoc supportent de nombreux autres formatages]. 2. Le balisage du texte Hyperliens simples <http://www.url.org> ou [avec un titre](http://fsf.org).  > Citation avec syntaxe similaire à ce > qui se pratique dans les courriels Droite Gauche Centre -------- ------- ---------- 12 12 12 123 123 123 1 1 1 Code : ~~~ {.Javascript} function AlertError() { alert(this.error); } ~~~ A Export au format PDF (via L TEX) : Export au format HTML (brut sans CSS) : Export au format ODT (brut sans template) : Gérons l'edoc source : Git Ah mais l'edoc c'est du source comme le code, donc c'est du texte ? Ben oui donc git clone ou git init, git add, git commit, git pull, éventuellement git diff, git merge et finalement git push !!! Donc ça y est, là on gère enfin le code et l'edoc de la même manière, avec les mêmes outils.