Copyright © 2003 Éric Bellot
2003-05-06
Résumé
Dn2dbk est une feuille de styles XSLT permettant la conversion d'un document RST (reStructuredText) au format Docbook. Elle fonctionne avec un processeur XSLT (Xsltproc, Saxon, Xalan, etc.)
Table des matières
Correction d'un bogue dans la conversion des attributs d'images (remerciements à Joachim Koenig-Baltes).
Grosse amélioration de Dn2dbk. A de rares exceptions près, l'intégralité d'un document RST peut être convertie.
Voir Référence de la conversion pour plus de détails.
dn2dbx.xsl est une feuille de XSLT permettant de convertir un document reStructuredText (RST) au format Docbook-XML. La chaîne de conversion est la suivante :
Document =====> Document =====> Document
RST Python + DN-XML Xsltproc + Docbook-XML
(*.txt) Docutils + (*.xml) dn2dbk.xsl (*.xml)
docutils-xml.py
|
dn2dbk.xsl supporte la quasi totalité de la syntaxe RST. Les détails de la conversion sont présentés dans la référence de la conversion (voir Reference).
Oliver Rutherfurd a réalisé un script Python (docbook.py) capable de convertir directement un document RST au format Docbook.
Le script docbook.py peut être télécharger sur http://docutils.sf.net/index.html#the-sandbox
Le ReStructuredText (RST) est une syntaxe permettant de rédiger des documents structurés en texte brut. Elle a été créé par David Goodger dans le cadre du projet Docutils.
Le RST est une syntaxe sans balises. Les documents sont réellement lisibles par un être humain, contrairement au XML/HTML pour lesquels le contenu du document est noyé au milieu des balises.
un document RST est donc rapide à rédiger, un simple éditeur de texte suffit (Vim, par exemple).
Les Docutils sont un ensemble de scripts Python permettant de gérer les documents RTS et de les convertir au format XML ou HTML.
Les Docutils sont livrés avec le script docutils-xml.py. Il permet de convertir facilement un document RST au format Docutils-native XML. C'est ce fichier XML que Dn2dbk converti au format Docbook.
Le répertoire dn2dbk contient :
dn2dbk.xsl
rst2dbk.txt (le document que vous lisez)
reference.txt (la reference de la conversion)
les versions Docutils Native, Docbook et HTML de ces documents
Dn2dbk est publié sous la license LGPL.
Le document Docbook produit à partir de rst2dbk.txt (la source du document que vous lisez) a été parsé et validé avec Xmllint pour Docbook 4.1.2, Docbook 4.2 et Simplified Docbook 1.0RC3.
Les logiciels suivant doivent être installés et opérationnels pour utiliser Dn2dbk :
Python est un langage de script multi-plateformes bien connu.
Docutils est une bibliothèque de scripts qui permet de gérer le format RST. Elle inclut notamment les scripts permettant de convertir un document RST au format Docutils-native XML.
La version 0.2.8 des Docutils est téléchargeable sous forme de snapshot. Evitez d'utiliser la version 0.2, assez obsolète.
Sur Linux-Mandrake 9.x, il faut installer les paquetages de développement de Python pour pouvoir installer les Docutils.
C'est un front-end en Python pour convertir un document RST au format XML (DN-XML). Il est fourni avec le pack Docutils, mais n'est pas installé avec lui.
Il se trouve dans le le répertoire tools de l'archive.
sous GNU/Linux, le plus simple est de le copier dans /usr/bin ou dans ~/bin. Puis de rendre le script exécutable
chmod a+x /usr/bin/docutils-xml.py |
sous Windows, c'est plus compliqué car il n'est pas possible de lancer directement un script Python.
Voici une méthode possible :
Créez un dossier C:\rst2dn (par exemple).
Copiez docutils-xml.py dans ce dossier.
Toujours dans ce dossier, faites un script Batch nommé, par exemple, rst2dn.bat contenant la ligne suivante
python docutils-xml.py %* |
Ajoutez le dossier C:\rst2dn à la variable PATH en insérant la ligne suivante dans C:\autoexec.bat:
set PATH=%PATH%;C:\rst2dn |
Il existe toute une série de processeurs XSLT. Je recommande Xsltproc. Il est fiable et (beaucoup) plus rapide que les autres. Il est néanmoins possible d'utiliser Saxon, Xalan, etc.
Placez la feuille dn2dbk.xsl où vous voulez et définissez une variable d'environnement qui pointe dessus.
Sous GNU/Linux, je place habituellement mes feuilles XSL dans mon répertoire perso : ~/xsl. J'ajoute donc la ligne suivante dans ~/bashrc :
export DN2DBK=~/xsl/dnxml2dbk.xsl |
Sous Windows, ajoutez la ligne suivante dans C:\autoexec.bat :
set DN2DBK = C:\xsl\dnxml2dbk.xsl |
Conversion RST vers DN-XML.
Sous GNU/Linux, la syntaxe est:
docutils-xml.py myrst.txt myrst-dn.xml |
Sous Windows:
rst2dnxml.bat myrst.txt myrst-dn.xml |
Conversion DN-XML vers Docbook-XML avec Xsltproc.
Je pars ici du principe que l'emplacement de la feuille XSLT dn2dbk.xsl a été référencé dans la variable d'environnement DN2DBK. Sinon, remplacez $DN2DBK ou %DN2DBK% par le chemin vers dn2dbk.xsl.
Sous GNU/Linux, la syntaxe est
xsltproc -o myrst-dbk.xml $DN2DBK myrst-dn.xml |
Sous Windows
xsltproc -o myrst-dbk.xml %DN2DBK% myrst-dn.xml |
Voir Reference
Ce document a été rédigé au format RST avec GVim puis converti au format Docbook avec dn2dbk.xsl.
La version HTML a été réalisée avec les feuilles XSLT de Norman Walsh (v. 1.60.1) à partir du document Docbook .
Afin de faciliter la consultation des sources, le code des fichiers XML est présenté au format HTML (la conversion a été réalisé avec Vim).
Vous trouverez les sources réelles dans l'archive dn2dbk-0.3.1.tar.gz
Format RST : rst2dbk.txt (la source réelle du document)
Code du fichier DN-XML : dn-rst2dbk.xml.html
Code du fichier Docbook-XML : dbk-rst2dbk.xml.html