======================================== Conversion reStructuredText vers Docbook ======================================== :Auteur: Éric Bellot :Contact: ebellot@laposte.net :Date: 2003-05-06 :Copyright: Copyright© 2003, Éric Bellot :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.) News ==== 2003-02-27 - Dn2dbk-0.3.1 Correction d'un bogue dans la conversion des attributs d'images (remerciements à Joachim Koenig-Baltes). 2003-02-19 - Dn2dbk-0.3 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. Présentation ============ Dn2dbk ------ ``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 : .. Code-interprété:: 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_). .. Note:: 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 ReStructuredText (RST) ---------------------- 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). Scripts Docutils ---------------- 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. Docbook ------- Docbook est une syntaxe d'organisation de documents SGML/XML destinée à la documentation informatique. Elle offre de puissantes possibilités de conversion (HTML, PDF, RTF, etc.). Dn2dbk produit un Docbook au format XML. Téléchargement ============== Dn2dbk-0.3.1.tar.gz_ (27 Ko) 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 `_. .. _dn2dbk-0.3.1.tar.gz: dn2dbk-0.3.1.tar.gz .. Note:: 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. Installation ============ Logiciels requis ---------------- Les logiciels suivant doivent être installés et opérationnels pour utiliser Dn2dbk : Python_ 2.2.x Python est un langage de script multi-plateformes bien connu. Docutils_ 0.2.8 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. .. Note:: Sur Linux-Mandrake 9.x, il faut installer les paquetages de développement de Python pour pouvoir installer les Docutils. Docutils-xml.py 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 : 1. Créez un dossier ``C:\rst2dn`` (par exemple). 2. Copiez ``docutils-xml.py`` dans ce dossier. 3. Toujours dans ce dossier, faites un script Batch nommé, par exemple, ``rst2dn.bat`` contenant la ligne suivante :: python docutils-xml.py %* 4. Ajoutez le dossier ``C:\rst2dn`` à la variable PATH en insérant la ligne suivante dans ``C:\autoexec.bat``: :: set PATH=%PATH%;C:\rst2dn Un processeur XSLT 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. .. _xsltproc: http://xmlsoft.org .. _saxon: http://saxon.sf.net .. _xalan: http://xml.apache.org Installation de Dn2dbk ---------------------- 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 Utilisation =========== 1) 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 2) 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 Référence de la conversion ========================== Voir Reference_ .. _Reference: reference/index.htm Aperçu des divers formats de ce document ======================================== 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 . .. _`feuilles XSLT de Norman Walsh`: http://docbook.sourceforge.net/projects/xsl/index.html .. _GVim: http://www.vim.org 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_ .. _rst2dbk.txt: rst2dbk.txt .. _dn-rst2dbk.xml.html: dn-rst2dbk.xml.html .. _dbk-rst2dbk.xml.html: dbk-rst2dbk.xml.html .. Liens ===== .. _Python: http://www.python.org .. _Docutils: http://docutils.sf.net .. _RST: http://docutils.sf.net/rst .. _dnxml2dbk.xsl: http://www.chez.com/ebellot/rest