1 <?xml version="1.0"?> 2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"> 3 <article lang="fr-FR"> 4 <articleinfo> 5 <title>Conversion reStructuredText vers Docbook</title> 6 <author> 7 <othername>Éric Bellot</othername> 8 </author> 9 <bibliomisc> 10 <email>ebellot@laposte.net</email> 11 </bibliomisc> 12 <pubdate>2003-02-19 20:55:11</pubdate> 13 <copyright> 14 <year>2003</year> 15 <holder>Éric Bellot</holder> 16 </copyright> 17 <legalnotice> 18 <para>Permission vous est donnée de copier, distribuer et/ou modifier ce 19 document selon les termes de la Licence GNU Free Documentation License, 20 Version 1.1 ou ultérieure publiée par la Free Software Foundation ;</para> 21 <para>Avec les sections inaltérables suivantes : La section "Licence"</para> 22 <para>La licence officielle peut être consultée sur le Web à l'adresse 23 suivante : <ulink url="http://www.gnu.org/licenses/fdl.html">http://www.gnu.org/licenses/fdl.html</ulink></para> 24 </legalnotice> 25 <abstract> 26 <para>Dn2dbk est une feuille de styles XSLT permettant la conversion d'un 27 document RST (reStructuredText) au format Docbook. Elle fonctionne 28 avec un processeur XSLT (Xsltproc, Saxon, Xalan, etc.)</para> 29 </abstract> 30 </articleinfo> 31 <section id="news"> 32 <title>News</title> 33 <variablelist role="definition_list"> 34 <varlistentry> 35 <term>2003-02-19</term> 36 <listitem> 37 <para>Grosse amélioration de Dn2dbk. A de rares exceptions, l'intégralité 38 d'un document RST peut être converti.</para> 39 <para>Voir <link linkend="r-f-rence-de-la-conversion">Référence de la conversion</link> pour plus de détails.</para> 40 </listitem> 41 </varlistentry> 42 </variablelist> 43 </section> 44 <section id="pr-sentation"> 45 <title>Présentation</title> 46 <section id="dn2dbk"> 47 <title>dn2dbk</title> 48 <para><literal>dn2dbx.xsl</literal> est une feuille de XSLT permettant de convertir un 49 document reStructuredText (RST) au format Docbook-XML. La chaîne de 50 conversion est la suivante :</para> 51 <programlisting>Document =====> Document =====> Document 52 RST Python + DN-XML Xsltproc + Docbook-XML 53 (*.txt) Docutils + (*.xml) dn2dbk.xsl (*.xml) 54 docutils-xml.py</programlisting> 55 <para><literal>dn2dbk.xsl</literal> est capable de convertir le quasi totalité de la syntaxe 56 RST. Toutefois, le RST et de la Docbook étant parfois différentes, on 57 trouvera plus bas les correspondances entre les éléments dissemblables 58 (voir <link linkend="r-f-rence-de-la-conversion">Référence de la conversion</link>).</para> 59 <note> 60 <para>Oliver Rutherfurd a réalisé un script Python (<literal>docbook.py</literal>) 61 capable de convertir directement un document RST au format Docbook.</para> 62 <para>Toutefois, <literal>Docbook.py</literal> est relativement incomplète et n'a pas 63 évoluée depuis plusieurs mois.</para> 64 <para>Le script <literal>docbook.py</literal> peut être télécharger sur 65 <ulink url="http://docutils.sf.net/index.html#the-sandbox">http://docutils.sf.net/index.html#the-sandbox</ulink></para> 66 </note> 67 </section> 68 <section id="restructuredtext"> 69 <title>reStructuredText</title> 70 <para>Le <emphasis role="strong">reStructuredText</emphasis> (RST) est une syntaxe permettant de rédiger des 71 documents structurés en texte brut. Elle a été créée par David Goodger 72 dans le cadre du projet <ulink url="http://docutils.sf.net">Docutils</ulink>.</para> 73 <para>Le RST est une syntaxe sans balises. Les documents sont réellement 74 lisibles par un être humain, contrairement au XML/HTML pour lesquels le 75 contenu du document est noyé au milieu des balises.</para> 76 <para>un document RST est donc rapide à rédiger, un simple éditeur de texte 77 suffit (Vim, par exemple).</para> 78 </section> 79 <section id="scripts-docutils"> 80 <title>Scripts Docutils</title> 81 <para>Les <emphasis role="strong">Docutils</emphasis> sont un ensemble de scripts Python permettant de gérer 82 le resStructuredText et de le convertir au format XML ou HTML.</para> 83 <para>Les docutils sont livrés avec le script <literal>docutils-xml.py</literal>. Il permet 84 de convertir facilement un document RST au format <emphasis role="strong">Docutils-native 85 XML</emphasis>. Le fichier XML produit obéit à la DTD Docutils qui reprend 86 l'intégralité de la syntaxe RST en XML.</para> 87 </section> 88 <section id="docbook"> 89 <title>Docbook</title> 90 <para><emphasis role="strong">Docbook</emphasis> est une syntaxe d'organisation de documents SGML/XML destinée à 91 la documentation informatique. Elle offre de puissantes possibilités de 92 conversion (HTML, PDF, RTF, etc.).</para> 93 <para>Dn2dbk produit un Docbook au format XML.</para> 94 </section> 95 </section> 96 <section id="t-l-chargement"> 97 <title>Téléchargement</title> 98 <variablelist role="definition_list"> 99 <varlistentry> 100 <term><ulink url="dn2dbk-0.3.tar.gz">Dn2dbk-0.3.tar.gz</ulink> (27 Ko)</term> 101 <listitem> 102 <para>Le répertoire <literal>dn2dbk</literal> contient :</para> 103 <itemizedlist mark="-"> 104 <listitem> 105 <para>dn2dbk.xsl</para> 106 </listitem> 107 <listitem> 108 <para>rst2dbk.txt (le document que vous lisez)</para> 109 </listitem> 110 <listitem> 111 <para>reference.txt (la reference de la conversion)</para> 112 </listitem> 113 <listitem> 114 <para>les versions Docutils Native, Docbook et HTML de ces documents</para> 115 </listitem> 116 </itemizedlist> 117 </listitem> 118 </varlistentry> 119 </variablelist> 120 </section> 121 <section id="installation"> 122 <title>Installation</title> 123 <section id="logiciels-requis"> 124 <title>Logiciels requis</title> 125 <para>Les logiciels doivent être installés et opérationnels</para> 126 <itemizedlist mark="-"> 127 <listitem> 128 <para><ulink url="http://www.python.org">Python</ulink> 2.2.x</para> 129 <para>Python est un langage de script multi-plateformes bien connu.</para> 130 </listitem> 131 <listitem> 132 <para><ulink url="http://docutils.sf.net">Docutils</ulink> 0.2.8</para> 133 <para>Docutils est une bibliothèque de scripts qui permet de gérer, entre 134 autres, le format RST. Elle inclue notamment les scripts permettant de 135 convertir un document RST au format Docutils-native XML.</para> 136 <para>La version 0.2.8 des Docutils est téléchargeable sous forme de 137 snapshot. Evitez d'utiliser la version 0.2, assez obsolète.</para> 138 <note> 139 <para>Sur Linux-Mandrake 9.x, il faut installer les paquetages de 140 développement de Python pour pouvoir installer les Docutils.</para> 141 </note> 142 </listitem> 143 <listitem> 144 <para>docutils-xml.py</para> 145 <para>C'est un front-end en Python pour convertir un document RST au format 146 XML (DN-XML). Il est fourni avec le pack Docutils, mais n'est pas 147 installé avec lui.</para> 148 <para>Il se trouve dans le le répertoire <literal>tools</literal> de l'archive.</para> 149 <itemizedlist mark="-"> 150 <listitem> 151 <para>sous GNU/Linux, le plus simple est de le copier dans <literal>/usr/bin</literal> ou 152 dans <literal>~/bin</literal>. Puis de rendre le script exécutable</para> 153 <programlisting>chmod a+x /usr/bin/docutils-xml.py</programlisting> 154 </listitem> 155 <listitem> 156 <para>sous Windows, c'est plus compliqué car il n'est pas possible de 157 lancer directement un script Python.</para> 158 <para>Voici la méthode que j'utilise :</para> 159 <orderedlist numeration="arabic"> 160 <listitem> 161 <para>Créez un dossier <literal>C:\rst2dn</literal> (par exemple).</para> 162 </listitem> 163 <listitem> 164 <para>Copiez <literal>docutils-xml.py</literal> dans ce dossier.</para> 165 </listitem> 166 <listitem> 167 <para>Toujours dans ce dossier, faites un script Batch nommé, par 168 exemple, <literal>rst2dn.bat</literal> contenant la ligne suivante</para> 169 <programlisting>python docutils-xml.py %*</programlisting> 170 </listitem> 171 <listitem> 172 <para>Ajouter le dossier <literal>C:\rst2dn</literal> à la variable PATH en insérant 173 la ligne suivante dans <literal>C:\autoexec.bat</literal>:</para> 174 <programlisting>set PATH=%PATH%;C:\rst2dn</programlisting> 175 </listitem> 176 </orderedlist> 177 </listitem> 178 </itemizedlist> 179 </listitem> 180 <listitem> 181 <para>un processeur XSLT</para> 182 <para>Il existe toute une série de processeurs XSLT. Je recommande 183 <ulink url="http://xmlsoft.org">Xsltproc</ulink>. Il est fiable et (beaucoup) plus rapide que les autres. Il 184 est néanmoins possible d'utiliser <ulink url="http://saxon.sf.net">Saxon</ulink>, <ulink url="http://xml.apache.org">Xalan</ulink>, etc.</para> 185 </listitem> 186 </itemizedlist> 187 </section> 188 <section id="installation-de-dn2dbk"> 189 <title>Installation de dn2dbk</title> 190 <para>Placez la feuille <literal>dn2dbk.xsl</literal> où vous voulez et définissez une 191 variable d'environnement qui pointe dessus.</para> 192 <itemizedlist mark="-"> 193 <listitem> 194 <para>Sous GNU/Linux, je place habituellement mes feuilles XSL dans mon 195 répertoire perso : <literal>~/xsl</literal>. J'ajoute donc la ligne suivante dans 196 <literal>~/bashrc</literal> :</para> 197 <programlisting>export DN2DBK=~/xsl/dnxml2dbk.xsl</programlisting> 198 </listitem> 199 <listitem> 200 <para>Sous Windows, ajoutez la ligne suivante dans <literal>C:\autoexec.bat</literal> :</para> 201 <programlisting>set DN2DBK = C:\xsl\dnxml2dbk.xsl</programlisting> 202 </listitem> 203 </itemizedlist> 204 </section> 205 </section> 206 <section id="utilisation"> 207 <title>Utilisation</title> 208 <orderedlist numeration="arabic"> 209 <listitem> 210 <para>Conversion RST vers DN-XML.</para> 211 <itemizedlist mark="-"> 212 <listitem> 213 <para>Sous GNU/Linux, la syntaxe est:</para> 214 <programlisting>docutils-xml.py myrst.txt myrst-dn.xml</programlisting> 215 </listitem> 216 <listitem> 217 <para>Sous Windows:</para> 218 <programlisting>rst2dnxml.bat myrst.txt myrst-dn.xml</programlisting> 219 </listitem> 220 </itemizedlist> 221 </listitem> 222 <listitem> 223 <para>Conversion DN-XML vers Docbook-XML avec Xsltproc.</para> 224 <para>Je pars ici du principe que l'emplacement de la feuille XSLT 225 <literal>dn2dbk.xsl</literal> a été référencé dans la variable d'environnement 226 <literal>DN2DBK</literal>. Sinon, remplacez <literal>$DN2DBK</literal> ou <literal>%DN2DBK%</literal> par le 227 chemin vers <literal>dn2dbk.xsl</literal>.</para> 228 <itemizedlist mark="-"> 229 <listitem> 230 <para>Sous GNU/Linux, la syntaxe est</para> 231 <programlisting>xsltproc -o myrst-dbk.xml $DN2DBK myrst-dn.xml</programlisting> 232 </listitem> 233 <listitem> 234 <para>Sous Windows</para> 235 <programlisting>xsltproc -o myrst-dbk.xml %DN2DBK% myrst-dn.xml</programlisting> 236 </listitem> 237 </itemizedlist> 238 </listitem> 239 </orderedlist> 240 </section> 241 <section id="r-f-rence-de-la-conversion"> 242 <title>Référence de la conversion</title> 243 <para>Voir <ulink url="ref/index.htm">Reference</ulink></para> 244 </section> 245 <section id="aper-u-des-divers-formats-de-ce-document"> 246 <title>Aperçu des divers formats de ce document</title> 247 <para>Ce document a été rédigé au format RST avec <ulink url="http://www.vim.or">GVim</ulink> puis converti au 248 format Docbook avec <literal>dn2dbk.xsl</literal>.</para> 249 <para>La version HTML a été réalisée avec les <ulink url="http://docbook.sourceforge.net/projects/xsl/index.html">feuilles XSLT de Norman Walsh</ulink> à 250 partir du document Docbook.</para> 251 <para>Afin de faciliter la consultation des sources, le code des fichier XML 252 est présenté au format HTML (la conversion à été réalisée avec Vim).</para> 253 <para>Vous trouverez les sources réelles dans l'archive <ulink url="dn2dbk-0.3.tar.gz">dn2dbk-0.3.tar.gz</ulink></para> 254 <itemizedlist mark="-"> 255 <listitem> 256 <para>Format RST : <ulink url="rst2dbk.txt">rst2dbk.txt</ulink> (la source réelle du document)</para> 257 </listitem> 258 <listitem> 259 <para>Code du fichier DN-XML : <ulink url="dn-rst2dbk.xml.html">dn-rst2dbk.xml.html</ulink></para> 260 </listitem> 261 <listitem> 262 <para>Code du fichier Docbook-XML : <ulink url="dbk-rst2dbk.xml.html">dbk-rst2dbk.xml.html</ulink></para> 263 </listitem> 264 </itemizedlist> 265 <!--Liens 266 =====--> 267 </section> 268 </article>