Le Markdown est un balisage qui se lit à l'œil nu, et le format que les modèles de langage lisent le mieux. L'AsciiDoc est le balisage qui fait ce que le Markdown ne fait pas, sans quitter le texte brut. pandoc se tient entre les deux, et cette page dit exactement ce qui arrive à un fichier MD en route vers l'AsciiDoc.
Ce qui s'exécute quand un fichier MD devient un AsciiDoc
pandoc en deux passes, sur une machine que nous louons et que nous surveillons. Votre fichier MD est envoyé une fois, pandoc s'exécute une fois, le fichier AsciiDoc revient, et aucun des deux fichiers n'est conservé. MD vers AsciiDoc fait partie des 3649 paires sur lesquelles ce moteur a été sondé avec un vrai fichier, et c'est pour cela que cette page existe quand celles que la sonde n'a pas su prouver n'existent pas.
Ce qui survit du fichier MD dans le fichier AsciiDoc
La hiérarchie des titres. pandoc analyse le fichier MD vers son propre arbre de document et écrit cet arbre en AsciiDoc, si bien qu'un titre de niveau deux reste un titre de niveau deux et non simplement du texte en gras.
Les tableaux, reconstruits en syntaxe AsciiDoc plutôt que photographiés. C'est la différence entre un tableau qu'une machine sait lire et l'image d'un tableau, et c'est toute la raison de faire passer un fichier MD par pandoc plutôt que par une imprimante.
Les listes du fichier MD, imbrications comprises, plus les blocs de code, les citations et les liens, tous réexprimés en AsciiDoc.
Les images : pandoc les extrait du fichier MD vers un répertoire de travail et les réintègre dans l'AsciiDoc, si bien que rien ne finit par pointer vers un fichier qui n'existe plus.
Ce que la conversion MD vers AsciiDoc vous coûte
La couche de présentation. pandoc ne traduit pas le fichier MD en AsciiDoc, il le reconstruit depuis son propre arbre de document : les styles personnalisés, la mise en page, les en-têtes et les pieds de page ne traversent pas. La structure, si, et c'est de cela que l'arbre est fait.
D'où viennent les fichiers MD et AsciiDoc
AsciiDoc. Écrit chez IBM en 2002 et maintenu en vie parce que le Markdown s'arrête là où commence la documentation technique : il n'a pas de norme pour les tableaux qui débordent d'une page, pas de blocs d'avertissement, aucun moyen d'inclure un fichier dans un autre. L'AsciiDoc a les trois. C'est dans ce format que le noyau Linux, Git et Fedora écrivent leur documentation.
Si un modèle doit lire le fichier AsciiDoc
La structure est ce qui subsiste du fichier MD, et la structure est ce dont un modèle a besoin. MD en entrée, AsciiDoc en sortie, avec l'arbre des titres intact plutôt qu'aplati en un seul long paragraphe.
MD vers AsciiDoc, mesuré plutôt que promis
En passant MD vers AsciiDoc sur le moteur réel avec un vrai fichier, pandoc a écrit 267 octets au format AsciiDoc en moins d'un dixième de seconde, machine par ailleurs au repos. C'est un fichier MD un jour donné et non une moyenne, et c'est pourquoi le nombre est donné avec le fichier qui l'a produit.
Le verdict MD vers AsciiDoc a été obtenu par la recherche d'un marqueur propre au format, et du mot témoin avec lui, c'est-à-dire que la sortie porte un marqueur qu'aucun autre format n'écrit, et le mot témoin planté dans la source y est encore. Rien ne sait relire ces cibles, les deux ont donc été exigés : le mot seul prouverait que le texte a voyagé, le marqueur seul que la forme est bonne. Le contrôle employé compte, parce qu'ils ne prouvent pas tous la même chose, et un code de statut 200 ne prouve strictement rien sur ce que le fichier AsciiDoc contient.
Le même fichier MD, envoyé ailleurs
Les autres sorties que la sonde a mesurées à partir d'un fichier MD, pour que le coût du choix du format AsciiDoc se lise face à quelque chose. Les tailles ne se comparent pas d'un moteur à l'autre, chaque famille ayant été sondée avec son propre fichier témoin MD.
MD vers PDF : 25 764 octets en 1,9 secondes, vérifié par une signature de format.
MD vers DOCX : 10 106 octets en 0,1 secondes, vérifié par un aller-retour pandoc.
MD vers EPUB : 5 034 octets en 0,1 secondes, vérifié par un aller-retour pandoc.
MD vers TXT : 264 octets en moins d'un dixième de seconde, vérifié par la relecture du texte.
MD vers HTML : 4 018 octets en 0,1 secondes, vérifié par un aller-retour pandoc.
MD vers RTF : 687 octets en moins d'un dixième de seconde, vérifié par un aller-retour pandoc.
Ce que nous ne prétendrons pas sur MD vers AsciiDoc
Un fichier MD de plus de 25 Mo est refusé avant la fin de l'envoi plutôt qu'après, pour que vous n'attendiez pas un refus.
Une conversion MD vers AsciiDoc qui dépasse 60 secondes est tuée, et le processus pandoc avec elle. Une exécution abandonnée resterait posée sur l'un des deux cœurs de la machine jusqu'à ce que quelqu'un le remarque.
32 des 935 paires sondées dans la famille qui sert MD vers AsciiDoc ont échoué, et celle-ci n'en fait pas partie. Elles échouent pour des raisons qu'il vaut mieux connaître : un rédacteur incapable de porter ce dont le document est fait, ou une sortie que le moteur n'a pas su relire. Elles sont comptées ici plutôt que cachées, parce qu'une paire qui échoue en silence est pire qu'une paire qui échoue bruyamment.
pandoc n'écrit jamais l'AsciiDoc en passant par un moteur TeX ici, et il n'écrit pas de PDF du tout : les onze moteurs qu'il lui faudrait ne sont pas sur cette machine, et une distribution TeX pèse plusieurs gigaoctets. Qui veut un PDF à partir d'un fichier MD passe par LibreOffice ou par calibre, qui en sont réellement capables.
Un fichier MD à la fois, choisi dans le navigateur. Il n'y a rien d'autre à régler et rien d'autre à proposer.
MD vers AsciiDoc : les questions que l'on pose
Qu'est-ce qui convertit vraiment mon fichier MD en AsciiDoc ?
C'est pandoc qui s'en charge, en deux passes, sur une machine que nous louons et que nous surveillons. Ni astuce de navigateur, ni service d'un tiers : le fichier MD est envoyé une fois, pandoc s'exécute une fois, l'AsciiDoc revient, et aucun des deux fichiers n'est conservé ensuite.
Combien de temps prend une conversion MD vers AsciiDoc ?
Sur le fichier utilisé par la sonde, pandoc a mis moins d'un dixième de seconde et écrit 267 octets d'AsciiDoc. C'est une mesure réelle sur un fichier MD réel, pas une moyenne et pas une promesse sur le vôtre : un MD plus gros prend plus longtemps, et au-delà de 60 secondes l'exécution est arrêtée.
Qu'est-ce que je perds en passant du MD à l'AsciiDoc ?
Celle qu'il faut connaître en premier : la couche de présentation. pandoc ne traduit pas le fichier MD en AsciiDoc, il le reconstruit depuis son propre arbre de document : les styles personnalisés, la mise en page, les en-têtes et les pieds de page ne traversent pas. La structure, si, et c'est de cela que l'arbre est fait.
Les tableaux de mon fichier MD sont-ils encore des tableaux dans l'AsciiDoc ?
Oui. pandoc lit les tableaux du MD dans son propre arbre de document et les réécrit en syntaxe AsciiDoc, si bien que vous obtenez un tableau qu'une machine sait analyser plutôt qu'une image de tableau.
La conversion MD vers AsciiDoc est-elle gratuite ?
Il y a une franchise gratuite chaque mois, et une conversion MD vers AsciiDoc y coûte un demi-crédit. Quand la franchise est épuisée, l'outil le dit et s'arrête, plutôt que de vous remettre discrètement un AsciiDoc moins bon.