Commit 5c293790 authored by Antoine Fauchié's avatar Antoine Fauchié

new: nouvelle fabrique, Asciidoctor

parent 3ddb2a15
@article{fauchie_repenser_2018,
title = {Repenser les cha\^ines de publication par l'int\'egration des pratiques du d\'eveloppement logiciel},
author = {Fauchi\'e, Antoine and Parisot, Thomas},
date = {2018},
journaltitle = {Sciences du Design},
volume = {n\textdegree{} 8},
pages = {45--56},
issn = {2428-3711},
url = {http://www.cairn.info/revue-sciences-du-design-2018-2-page-45.htm},
urldate = {2018-12-14},
abstract = {La rencontre des univers du livre et du d\&\#233;veloppement logiciel est \&\#224; l\&\#8217;\&\#339;uvre dans plusieurs exp\&\#233;rimentations de cha\&\#238;nes \&\#233;ditoriales, faisant appara\&\#238;tre de nouvelles approches et de nouvelles pratiques de design. Les \&\#233;tapes du processus d\&\#8217;\&\#233;dition sont r\&\#233;\&\#233;valu\&\#233;es, repens\&\#233;es, re-con\&\#231;ues, notamment par l\&\#8217;av\&\#232;nement d\&\#8217;un environnement profond\&\#233;ment num\&\#233;rique. Quelles sont les influences des m\&\#233;thodes et des outils du d\&\#233;veloppement web sur les cha\&\#238;nes de publication des livres\&\#160;? Nous nous focaliserons ici sur quatre aspects\&\#160;: la modularit\&\#233; des \&\#233;tapes et outils d\&\#8217;\&\#233;dition, l\&\#8217;ouverture des formats, la r\&\#233;duction de la distance entre le contenu et ses usages et l\&\#8217;\&\#233;conomie acquise qui concerne principalement l\&\#8217;humain. Cet article constitue un bref panorama des efforts n\&\#233;cessaires pour envisager une \&\#233;volution des cha\&\#238;nes d\&\#8217;\&\#233;dition, en sollicitant les pens\&\#233;es d\&\#8217;Ivan Illich et de Gilbert Simondon. Nous interrogerons des syst\&\#232;mes innovants inspir\&\#233;s de la m\&\#233;thode Agile, ch\&\#232;re au monde du d\&\#233;veloppement logiciel.},
file = {/home/antoine/Zotero/storage/JMILSF9C/Fauchié et Parisot - 2018 - Repenser les chaînes de publication par l’intégrat.pdf;/home/antoine/Zotero/storage/3VSAG9C2/revue-sciences-du-design-2018-2-page-45.html},
langid = {french},
number = {2}
}
@thesis{fauchie_vers_2018-1,
title = {Vers un syst\`eme modulaire de publication: m\'emoire de Master Publication num\'erique, Enssib, sous la direction d'Anthony Masure et Marcello Vitali-Rosati},
author = {Fauchi\'e, Antoine},
date = {2018},
institution = {{\'Ecole nationale sup\'erieure des sciences de l'information et des biblioth\`eques}},
location = {{Villeurbanne, France}},
url = {https://memoire.quaternum.net},
urldate = {2019-01-31},
abstract = {Vers un syst\`eme modulaire de publication~: \'editer avec le num\'erique. M\'emoire d'Antoine Fauchi\'e sur les cha\^ines de publication.},
file = {/home/antoine/Zotero/storage/H98F9WLM/memoire.quaternum.net.html},
langid = {french},
type = {M\'emoire}
}
@online{grossetie_awesome_2020,
title = {Awesome {{Asciidoctor}}.Js: {{Create PDF}} Using {{Web}} Technologies},
author = {Grossetie, Guillaume},
date = {2020-03-29},
journaltitle = {Yuzu tech},
url = {https://blog.yuzutech.fr/blog/asciidoctor-pdf-using-web-technologies/},
urldate = {2020-05-03},
file = {/home/antoine/Zotero/storage/HF5R6GF7/asciidoctor-pdf-using-web-technologies.html},
langid = {english},
type = {Blog}
}
@book{hamilton_docbook_2010,
title = {{{DocBook}} 5: {{The Definitive Guide}}},
shorttitle = {{{DocBook}} 5},
author = {Hamilton, Richard L., Norman Walsh},
date = {2010},
publisher = {{O'Reilly Media}},
url = {http://shop.oreilly.com/product/9780596805012.do},
urldate = {2018-07-25},
abstract = {If you need a reliable tool for technical documentation, this clear and concise reference will help you take advantage of DocBook, the popular XML schema originally developed to document computer and hardware projects. DocBook 5: The Definitive...},
file = {/home/antoine/Zotero/storage/7LYHFGGY/9780596805012.html},
isbn = {978-0-596-80502-9},
langid = {english}
}
@software{noauthor_asciidoctor_2020,
title = {Asciidoctor},
date = {2020-05-02T00:53:01Z},
origdate = {2012-06-01T19:09:20Z},
url = {https://github.com/asciidoctor/asciidoctor},
urldate = {2020-05-02},
abstract = {:gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.},
keywords = {asciidoc,asciidoctor,converter,docbook,html,manpage,ruby},
organization = {{Asciidoctor}}
}
@book{parisot_node.js_2018,
title = {Node.js: Apprendre par la pratique},
shorttitle = {Node.js},
author = {Parisot, Thomas},
date = {2018},
publisher = {{Eyrolles}},
location = {{Paris, France}},
abstract = {Plus de 500 exemples pour apprendre en pratiquantLa plate-forme Node.js est pass\'ee du statut d'OVNI \`a celui d'incontournable. En 2018, elle fait fonctionner des applications web, de l'outillage front-end, de la distribution de fichiers pair-\`a-pair, des objets connect\'es et la NASA l'utilise m\^eme pour analyser les donn\'ees t\'el\'em\'etriques de ses sondes spatiales.L'intention de cet ouvrage est d'\^etre votre base de d\'epart pour comprendre ce qu'il se passe dans cet \'ecosyst\`eme en perp\'etuel mouvement. Il devrait vous permettre de faire des choix techniques durables et de vous rendre op\'erationnelle sur LA plate-forme JavaScript, le langage le plus populaire du monde selon GitHub.Nous allons parcourir ensemble l'\'ecosyst\`eme Node.js en partant de son historique et de sa gouvernance jusqu'au d\'eploiement en continu de nos applications. Nous (re)partirons sur des bases solides de JavaScript pour ensuite d\'ecouvrir petit \`a petit le potentiel des modules Node.js. Ces connaissances sont les fondations pour explorer la conception, le d\'eveloppement et le d\'eploiement d'applications web, d'utilitaires en lignes de commandes et d'applications front-end modernes. Une s\'election vari\'ee de modules compl\'ementaires vous permettra d'y voir plus clair parmi les centaines de milliers de contributions de la communaut\'e Node.js.Plusieurs centaines d'exemples ponctuent l'ouvrage pour mieux cerner les concepts et leurs r\'esultats. Ils sont ex\'ecutables dans un terminal gr\^ace \`a un module npm ou dans un navigateur web gr\^ace \`a une surcouche interactive.\`A qui cet ouvrage s'adresse-t-il~?Aux d\'eveloppeurs et d\'eveloppeuses qui veulent se reconvertir depuis un autre langage de programmation comme P\'eri, PHP ou RubyAux d\'eveloppeurs et d\'eveloppeuses qui cherchent \`a tirer parti de l'outillage npm front-end\`A toute personne autodidacte et d\'esireuse de renforcer ses comp\'etences en programmation web},
isbn = {978-2-212-13993-8},
langid = {french},
pagetotal = {454}
}
@video{web_en_vert_documentation_2016,
title = {Documentation as code (expliqu\'e \`a mon p\`ere) \textemdash{} Hubert Sablonni\`ere},
editor = {{Web en Vert}},
date = {2016},
url = {https://www.youtube.com/watch?v=1rKgVF5CEEY},
urldate = {2017-12-01},
editortype = {director},
langid = {french}
}
......@@ -40,6 +40,7 @@ Pour naviguer dans ces _technologies de l'édition numérique_, la consultation
1. [LaTeX](/2020/04/29/fabriques-de-publication-latex/)
2. [Pandoc](/2020/04/30/fabriques-de-publication-pandoc/)
3. [Asciidoctor](/2020/05/03/fabriques-de-publication-asciidoctor/)
## Pour suivre cette série
......
---
layout: post
title: "Fabriques de publication : Asciidoctor"
date: 2020-05-03 22:00
comments: true
published: true
description: "Troisième analyse d'une série sur les fabriques de publication : Asciidoctor"
categories:
- carnet
- phd
classement:
- phd
status: brouillon
---
Troisième analyse d'une série sur les fabriques de publication : Asciidoctor.
<!-- more -->
[Introduction et liste des fabriques](/fabriques)
Asciidoctor est un processeur de texte et une chaîne de publication qui convertit le format de balisage léger AsciiDoc en différents formats de sortie comme HTML, PDF ou DocBook (un schéma XML).
## Description
Le fonctionnement d'Asciidoctor est très bien expliqué, y compris en français, sur le dépôt accueillant le code de ce programme écrit en Ruby : [https://github.com/asciidoctor/asciidoctor/](https://github.com/asciidoctor/asciidoctor/).
Pour faire une comparaison avec deux fabriques de publication [déjà présentées ici](/fabriques), l'association d'Asciidoctor et d'AsciiDoc est assez proche de celle de Pandoc et de Markdown.
D'un côté un langage de balisage léger, ici AsciiDoc, plus riche que Markdown et qui permet de structurer des textes complexes, et pensé plus spécifiquement pour de la documentation.
De l'autre Asciidoctor, un processeur conçu pour transformer ce balisage léger en d'autres formats, principalement HTML et DocBook, mais également PDF.
Asciidoctor est bien plus qu'un processeur, puisqu'il est accompagné de plusieurs modules ou bibliothèques qui viennent augmenter les fonctionnalités initiales.
Nous pouvons mentionner [asciidoctor-bibtex](https://github.com/asciidoctor/asciidoctor-bibtex/), un _package_ qui ajoute la possibilité d'intégrer des citations bibliographiques ou des bibliographies dans un document AsciiDoc, via une source de références en BibTeX.
Citons également [asciidoctor-reveal.js](https://github.com/asciidoctor/asciidoctor-reveal.js), destiné à générer des présentations [Reveal.js](https://github.com/hakimel/reveal.js) à partir d'une source AsciiDoc.
Il y a beaucoup d'autres possibilités d'export (notamment le format du livre numérique EPUB), les seules contraintes sont des informations d'entête à ajouter dans le document source, ou parfois des balisages spécifiques.
Ces _extensions_ peuvent être gérées avec [Bundle](https://bundler.io/), un moyen assez simple d'installer différents programmes en Ruby, de les garder à jour et de pouvoir déplacer tout cela au besoin.
Précisons qu'en plus d'être plus riche que Markdown, AsciiDoc (associé à Asciidoctor) introduit une dimension supplémentaire : le processeur reconstruit un arbre sémantique lorsqu'il parse la source en AsciiDoc, ce qui permet d'intégrer des fonctions intéressantes comme l'affichage de données pour un format d'export spécifique (typiquement ne pas intégrer une vidéo dans un export PDF, contrairement à un export HTML), ou l'utilisation de variables dans l'entête du document AsciiDoc.
Markdown peut permettre ce type de manipulation, mais il faut alors l'associer à un format de description de données comme [YAML](https://yaml.org/), voir ajouter des scripts spécifiques.
AsciiDoc et Asciidoctor le proposent par défaut, cet avantage peut devenir une contrainte – nous le verrons plus bas.
Pour utiliser AsciiDoc et Asciidoctor depuis plusieurs années, je peux témoigner de sa facilité d'usage et de sa puissance.
Pendant deux années j'ai créé tous mes supports de cours (une quinzaine de cours différents, probablement un cinquantaine de supports au total) avec Asciidoctor, produisant deux ou trois sorties différentes à partir de la même source : PDF pour imprimer les supports pour les étudiants (format A4 paginé), Reveal.js (HTML) pour les projections pendant les séances, et parfois HTML pour consulter les contenus dans un navigateur (j'ai toujours en projet d'expliquer plus précisément cette chaîne).
## Histoire
À l'origine AsciiDoc est un format de balisage **et** un processeur, d'abord pensé pour produire le format DocBook {% cite hamilton_docbook_2010 --file analyses-asciidoctor.bib %}, un schéma XML utilisé pour produire des livres techniques.
O'Reilly a utilisé ce format pendant longtemps, et d'ailleurs sa plateforme Atlas est basée sur AsciiDoc.
J'en ai parlé dans mon mémoire dans l'étude de cas consacrée à O'Reilly {% cite fauchie_vers_2018-1 --file analyses-asciidoctor.bib %}.
DocBook est un schéma XML qui correspond à des usages dans le domaine de la documentation technique, et qui fonctionne très bien pour des livres sur l'informatique par exemple.
L'avantage avec le XML c'est que potentiellement il peut être transformer en presque n'importe quoi, à condition de passer par des règles de conversion complexes en XSL.
AsciiDoc, en tant que processeur, n'est plus mis à jour depuis 2013 (http://asciidoc.org/CHANGELOG.html), et Asciidoctor semble l'avoir remplacé.
Aujourd'hui Asciidoctor est un véritable moteur pour le format de balisage AsciiDoc, avec une communauté très active – menée par l'infatigable [Dan Allen](https://github.com/mojavelinux).
## Specimen
Le projet [Antora](https://antora.org/) donne une bonne vision de ce que peuvent permettre AsciiDoc et Asciidoctor, j'y reviens plus bas.
Pour un exemple dans un domaine relativement classique d'édition de livre, l'ouvrage de Thomas Parisot {% cite parisot_node.js_2018 --file analyses-asciidoctor.bib %} illustre parfaitement la puissance d'Asciidoctor :
- une seule source : des chapitres au format AsciiDoc ;
- plusieurs formats de sortie : ODT pour l'éditeur qui retravaille le document avant de l'éditer dans InDesign, HTML pour la version web qui intègre des exemples de code exécutables ;
- du déploiement continu pour la version web consultable en ligne : [https://oncletom.io/node.js/](https://oncletom.io/node.js/).
## Critique
La communauté d'Asciidoctor promeut une gestion de la documentation proche de celle du code avec le slogan "Doc as Code" : fichiers texte, versionnement, _single source publishing_, déploiement continu.
Et nous ne pouvons que faire le constat que cela fonctionne, la question étant de savoir si cela peut correspondre à des usages en dehors du domaine de l'informatique ou de la communauté des développeurs et des développeuses, Hubert Sablonnière en parle très bien {% cite web_en_vert_documentation_2016 --file analyses-asciidoctor.bib %}.
Il est possible d'envisager quelque chose comme _book as code_, mais pour cela il faut disposer d'interfaces intermédiaires facilitant la compréhension et la manipulation.
J'en reparlerai dans le cas d'autres fabriques.
Asciidoctor a une dimension monolithique : il est dépendant du format de balisage AsciiDoc – plus étendu que Markdown mais encore limité –, et est principalement pensé pour un usage, la documentation.
En revanche il faut noter que Asciidoctor est porté dans un autre langage de programmation, JavaScript, par l'intermédiaire de Guillaume Grossetie, ce qui donne [Asciidoctor.js](https://github.com/asciidoctor/asciidoctor.js).
Également, si je critique ce monolithisme partiel, Asciidoctor s'interconnecte avec d'autres outils ou environnements, permettant de contourner certaines contraintes comme la génération de PDF à la mise en forme avancée {% cite grossetie_awesome_2020 --file analyses-asciidoctor.bib %}.
Comme Markdown, AsciiDoc est détourné pour des usages intéressants.
Le dernier exemple, qui donne matière à réflexion sur la nécessité d'envisager sérieusement l'utilisation de langages de balisage léger dans l'édition scientifique, c'est [asciidoctor-tei](https://github.com/Mogztter/asciidoctor-tei), développé par Guillaume Grossetie et Thomas Parisot.
Il s'agit d'une preuve de concept, l'objectif étant de générer, à partir d'un document balisé en AsciiDoc, un document XML respectant le schéma TEI d'OpenEdition.
## Vers d'autres fabriques
Deux projets ont déjà été cités ici : [Atlas](https://atlas.oreilly.com/), la chaîne de publication de l'éditeur O'Reilly, et Antora.
Je vais uniquement m'attarder sur [Antora](https://antora.org/) : il s'agit d'un générateur de site statique, basé sur AsciiDoc et Asciidoctor, et pensé pour produire de la documentation.
Antora répond à des besoins spécifiques, comme le fait de pouvoir disposer de plusieurs versions d'une même documentation adaptée à différentes versions d'un même logiciel, ou le fait d'intégrer des sources provenant de différents dépôts Git.
## Références
{% bibliography --file analyses-pandoc.bib %}
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment