Convertisseur en ligne gratuit de ASCIIDOC en DOCBOOK

Ce qu’est le format ASCIIDOC

AsciiDoc est un format de balisage en texte brut destiné à la documentation technique, aux manuels, aux fichiers README, aux livres et à la documentation web. Les auteurs rédigent des fichiers source lisibles portant des extensions telles que .adoc ou .asciidoc, en utilisant des conventions pour les titres, les listes, les avertissements, les tableaux, les liens, les images, le code source, les attributs et les inclusions.

Le principal logiciel utilisé pour créer et traiter les documents AsciiDoc est Asciidoctor, un convertisseur basé sur Ruby avec des implémentations pour d’autres environnements d’exécution. L’ancien processeur asciidoc prend également en charge ce format. Vous rencontrez ces fichiers dans les dépôts de logiciels, les projets de documentation, les flux de travail de sites statiques et les packages source.

Ce qu’est le format DOCBOOK

DocBook est un vocabulaire XML destiné aux livres structurés, aux manuels, aux articles, aux pages de référence et à d’autres publications techniques. Un fichier DocBook stocke des éléments sémantiques tels que <section>, <para>, <itemizedlist>, <programlisting> et <figure>, plutôt qu’une mise en forme spécifique à la présentation.

DocBook est utile lorsqu’un outil de publication XML, un système de gestion de contenu, un processus de validation ou un flux de travail d’archivage nécessite un format source standardisé. La sortie DocBook peut être transformée avec des outils tels que publican, dblatex, FOP ou des feuilles de style XSLT. DocBook 5 utilise des espaces de noms XML et un schéma moderne ; les anciens flux de travail peuvent nécessiter une sortie DocBook 4.

Comment convertir ASCIIDOC en DOCBOOK

Asciidoctor fournit la conversion la plus directe. Installez-le via RubyGems, puis exécutez :

gem install asciidoctor
asciidoctor -b docbook5 -o manual.xml manual.adoc

L’option -b docbook5 sélectionne la sortie DocBook 5, -o manual.xml définit le nom du fichier de destination et manual.adoc est le fichier source. Pour écrire le résultat à côté de la source avec un nom généré automatiquement, utilisez :

asciidoctor -b docbook5 manual.adoc

Pour un projet complet dont la source inclut d’autres fichiers, exécutez la commande depuis le répertoire du projet et vérifiez que les chemins relatifs des inclusions et des images sont corrects. Asciidoctor résout les fichiers inclus pendant la conversion : les fichiers manquants peuvent donc provoquer des erreurs ou produire une sortie incomplète. Des attributs peuvent être fournis sur la ligne de commande, par exemple :

asciidoctor -b docbook5 -a toc -a source-highlighter=highlight.js -o manual.xml manual.adoc

Utilisez -b docbook4 uniquement lorsque l’application destinataire ne peut pas traiter DocBook 5 :

asciidoctor -b docbook4 -o manual.xml manual.adoc

Pour une conversion sans installation, le convertisseur intégré de 101convert.com peut convertir le fichier gratuitement. Téléchargez le XML obtenu et examinez-le avant de l’importer dans un flux de publication.

Considérations relatives à la qualité et à la compatibilité

La sortie est une conversion structurelle, et non une copie visuelle d’un document rendu. Les attributs AsciiDoc, les rôles personnalisés, les extensions, les macros, le HTML intégré, les diagrammes et les types de blocs non pris en charge peuvent nécessiter un ajustement manuel ou une extension Asciidoctor. Les images sont normalement référencées par leur chemin plutôt qu’intégrées dans le XML : copiez donc le répertoire des images et préservez les emplacements relatifs attendus par le processeur DocBook.

Validez le résultat par rapport au schéma requis par l’outil suivant. Les documents DocBook 5 utilisent un espace de noms, tandis que les documents DocBook 4 utilisent une déclaration et des conventions d’éléments différentes. Vérifiez également les listes de code, les tableaux, les avertissements, les références croisées, les notes de bas de page et les fichiers inclus, car le comportement spécifique au backend peut différer du rendu AsciiDoc d’origine.