1 <?xml version="1.0" encoding="utf-8"?> 2 <!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML" "http://docutils.sourceforge.net/spec/docutils.dtd"> 3 <!-- Generated by Docutils 0.2.8 --> 4 <document id="conversion-restructuredtext-vers-docbook" name="conversion restructuredtext vers docbook" source="rst2dbk.txt"> 5 <title> 6 Conversion reStructuredText vers Docbook 7 </title> 8 <docinfo> 9 <author> 10 Ă~Iric Bellot 11 </author> 12 <contact> 13 <reference refuri="mailto:ebellot@laposte.net"> 14 ebellot@laposte.net 15 </reference> 16 </contact> 17 <date> 18 2003-02-19 20:55:11 19 </date> 20 <status> 21 Draft 22 </status> 23 <field> 24 <field_name> 25 lang 26 </field_name> 27 <field_body> 28 <paragraph> 29 fr-FR 30 </paragraph> 31 </field_body> 32 </field> 33 <copyright> 34 Copyright© 2003, Ă~Iric Bellot 35 </copyright> 36 <field> 37 <field_name> 38 legalnotice 39 </field_name> 40 <field_body> 41 <paragraph> 42 Permission vous est donnĂ©e de copier, distribuer et/ou modifier ce 43 document selon les termes de la Licence GNU Free Documentation License, 44 Version 1.1 ou ultĂ©rieure publiĂ©e par la Free Software Foundation ; 45 </paragraph> 46 <paragraph> 47 Avec les sections inaltĂ©rables suivantes : La section "Licence" 48 </paragraph> 49 <paragraph> 50 La licence officielle peut ĂȘtre consultĂ©e sur le Web Ă| l'adresse 51 suivante : 52 <reference refuri="http://www.gnu.org/licenses/fdl.html"> 53 http://www.gnu.org/licenses/fdl.html 54 </reference> 55 </paragraph> 56 </field_body> 57 </field> 58 </docinfo> 59 <topic class="abstract"> 60 <title> 61 Abstract 62 </title> 63 <paragraph> 64 Dn2dbk est une feuille de styles XSLT permettant la conversion d'un 65 document RST (reStructuredText) au format Docbook. Elle fonctionne 66 avec un processeur XSLT (Xsltproc, Saxon, Xalan, etc.) 67 </paragraph> 68 </topic> 69 <section id="news" name="news"> 70 <title> 71 News 72 </title> 73 <definition_list> 74 <definition_list_item> 75 <term> 76 2003-02-19 77 </term> 78 <definition> 79 <paragraph> 80 Grosse amĂ©lioration de Dn2dbk. A de rares exceptions, l'intĂ©gralitĂ© 81 d'un document RST peut ĂȘtre converti. 82 </paragraph> 83 <paragraph> 84 Voir 85 <reference refid="r-f-rence-de-la-conversion"> 86 RĂ©fĂ©rence de la conversion 87 </reference> 88 pour plus de dĂ©tails. 89 </paragraph> 90 </definition> 91 </definition_list_item> 92 </definition_list> 93 </section> 94 <section id="pr-sentation" name="prĂ©sentation"> 95 <title> 96 PrĂ©sentation 97 </title> 98 <section id="dn2dbk" name="dn2dbk"> 99 <title> 100 dn2dbk 101 </title> 102 <paragraph> 103 <literal> 104 dn2dbx.xsl 105 </literal> 106 est une feuille de XSLT permettant de convertir un 107 document reStructuredText (RST) au format Docbook-XML. La chaĂźne de 108 conversion est la suivante : 109 </paragraph> 110 <literal_block xml:space="preserve"> 111 Document =====> Document =====> Document 112 RST Python + DN-XML Xsltproc + Docbook-XML 113 (*.txt) Docutils + (*.xml) dn2dbk.xsl (*.xml) 114 docutils-xml.py 115 </literal_block> 116 <paragraph> 117 <literal> 118 dn2dbk.xsl 119 </literal> 120 est capable de convertir le quasi totalitĂ© de la syntaxe 121 RST. Toutefois, le RST et de la Docbook Ă©tant parfois diffĂ©rentes, on 122 trouvera plus bas les correspondances entre les Ă©lĂ©ments dissemblables 123 (voir 124 <reference refid="r-f-rence-de-la-conversion"> 125 RĂ©fĂ©rence de la conversion 126 </reference> 127 ). 128 </paragraph> 129 <note> 130 <paragraph> 131 Oliver Rutherfurd a rĂ©alisĂ© un script Python ( 132 <literal> 133 docbook.py 134 </literal> 135 ) 136 capable de convertir directement un document RST au format Docbook. 137 </paragraph> 138 <paragraph> 139 Toutefois, 140 <literal> 141 Docbook.py 142 </literal> 143 est relativement incomplĂšte et n'a pas 144 Ă©voluĂ©e depuis plusieurs mois. 145 </paragraph> 146 <paragraph> 147 Le script 148 <literal> 149 docbook.py 150 </literal> 151 peut ĂȘtre tĂ©lĂ©charger sur 152 153 <reference refuri="http://docutils.sf.net/index.html#the-sandbox"> 154 http://docutils.sf.net/index.html#the-sandbox 155 </reference> 156 </paragraph> 157 </note> 158 </section> 159 <section id="restructuredtext" name="restructuredtext"> 160 <title> 161 reStructuredText 162 </title> 163 <paragraph> 164 Le 165 <strong> 166 reStructuredText 167 </strong> 168 (RST) est une syntaxe permettant de rĂ©diger des 169 documents structurĂ©s en texte brut. Elle a Ă©tĂ© crĂ©Ă©e par David Goodger 170 dans le cadre du projet 171 <reference refuri="http://docutils.sf.net"> 172 Docutils 173 </reference> 174 . 175 </paragraph> 176 <paragraph> 177 Le RST est une syntaxe sans balises. Les documents sont rĂ©ellement 178 lisibles par un ĂȘtre humain, contrairement au XML/HTML pour lesquels le 179 contenu du document est noyĂ© au milieu des balises. 180 </paragraph> 181 <paragraph> 182 un document RST est donc rapide Ă| rĂ©diger, un simple Ă©diteur de texte 183 suffit (Vim, par exemple). 184 </paragraph> 185 </section> 186 <section id="scripts-docutils" name="scripts docutils"> 187 <title> 188 Scripts Docutils 189 </title> 190 <paragraph> 191 Les 192 <strong> 193 Docutils 194 </strong> 195 sont un ensemble de scripts Python permettant de gĂ©rer 196 le resStructuredText et de le convertir au format XML ou HTML. 197 </paragraph> 198 <paragraph> 199 Les docutils sont livrĂ©s avec le script 200 <literal> 201 docutils-xml.py 202 </literal> 203 . Il permet 204 de convertir facilement un document RST au format 205 <strong> 206 Docutils-native 207 XML 208 </strong> 209 . Le fichier XML produit obĂ©it Ă| la DTD Docutils qui reprend 210 l'intĂ©gralitĂ© de la syntaxe RST en XML. 211 </paragraph> 212 </section> 213 <section id="docbook" name="docbook"> 214 <title> 215 Docbook 216 </title> 217 <paragraph> 218 <strong> 219 Docbook 220 </strong> 221 est une syntaxe d'organisation de documents SGML/XML destinĂ©e Ă| 222 la documentation informatique. Elle offre de puissantes possibilitĂ©s de 223 conversion (HTML, PDF, RTF, etc.). 224 </paragraph> 225 <paragraph> 226 Dn2dbk produit un Docbook au format XML. 227 </paragraph> 228 </section> 229 </section> 230 <section id="t-l-chargement" name="tĂ©lĂ©chargement"> 231 <title> 232 TĂ©lĂ©chargement 233 </title> 234 <definition_list> 235 <definition_list_item> 236 <term> 237 <reference refuri="dn2dbk-0.3.tar.gz"> 238 Dn2dbk-0.3.tar.gz 239 </reference> 240 (27 Ko) 241 </term> 242 <definition> 243 <paragraph> 244 Le rĂ©pertoire 245 <literal> 246 dn2dbk 247 </literal> 248 contient : 249 </paragraph> 250 <bullet_list bullet="-"> 251 <list_item> 252 <paragraph> 253 dn2dbk.xsl 254 </paragraph> 255 </list_item> 256 <list_item> 257 <paragraph> 258 rst2dbk.txt (le document que vous lisez) 259 </paragraph> 260 </list_item> 261 <list_item> 262 <paragraph> 263 reference.txt (la reference de la conversion) 264 </paragraph> 265 </list_item> 266 <list_item> 267 <paragraph> 268 les versions Docutils Native, Docbook et HTML de ces documents 269 </paragraph> 270 </list_item> 271 </bullet_list> 272 </definition> 273 </definition_list_item> 274 </definition_list> 275 <target id="dn2dbk-0-3-tar-gz" name="dn2dbk-0.3.tar.gz" refuri="dn2dbk-0.3.tar.gz"/> 276 </section> 277 <section id="installation" name="installation"> 278 <title> 279 Installation 280 </title> 281 <section id="logiciels-requis" name="logiciels requis"> 282 <title> 283 Logiciels requis 284 </title> 285 <paragraph> 286 Les logiciels doivent ĂȘtre installĂ©s et opĂ©rationnels 287 </paragraph> 288 <bullet_list bullet="-"> 289 <list_item> 290 <paragraph> 291 <reference refuri="http://www.python.org"> 292 Python 293 </reference> 294 2.2.x 295 </paragraph> 296 <paragraph> 297 Python est un langage de script multi-plateformes bien connu. 298 </paragraph> 299 </list_item> 300 <list_item> 301 <paragraph> 302 <reference refuri="http://docutils.sf.net"> 303 Docutils 304 </reference> 305 0.2.8 306 </paragraph> 307 <paragraph> 308 Docutils est une bibliothĂšque de scripts qui permet de gĂ©rer, entre 309 autres, le format RST. Elle inclue notamment les scripts permettant de 310 convertir un document RST au format Docutils-native XML. 311 </paragraph> 312 <paragraph> 313 La version 0.2.8 des Docutils est tĂ©lĂ©chargeable sous forme de 314 snapshot. Evitez d'utiliser la version 0.2, assez obsolĂšte. 315 </paragraph> 316 <note> 317 <paragraph> 318 Sur Linux-Mandrake 9.x, il faut installer les paquetages de 319 dĂ©veloppement de Python pour pouvoir installer les Docutils. 320 </paragraph> 321 </note> 322 </list_item> 323 <list_item> 324 <paragraph> 325 docutils-xml.py 326 </paragraph> 327 <paragraph> 328 C'est un front-end en Python pour convertir un document RST au format 329 XML (DN-XML). Il est fourni avec le pack Docutils, mais n'est pas 330 installĂ© avec lui. 331 </paragraph> 332 <paragraph> 333 Il se trouve dans le le rĂ©pertoire 334 <literal> 335 tools 336 </literal> 337 de l'archive. 338 </paragraph> 339 <bullet_list bullet="-"> 340 <list_item> 341 <paragraph> 342 sous GNU/Linux, le plus simple est de le copier dans 343 <literal> 344 /usr/bin 345 </literal> 346 ou 347 dans 348 <literal> 349 ~/bin 350 </literal> 351 . Puis de rendre le script exĂ©cutable 352 </paragraph> 353 <literal_block xml:space="preserve"> 354 chmod a+x /usr/bin/docutils-xml.py 355 </literal_block> 356 </list_item> 357 <list_item> 358 <paragraph> 359 sous Windows, c'est plus compliquĂ© car il n'est pas possible de 360 lancer directement un script Python. 361 </paragraph> 362 <paragraph> 363 Voici la mĂ©thode que j'utilise : 364 </paragraph> 365 <enumerated_list enumtype="arabic" prefix="" suffix="."> 366 <list_item> 367 <paragraph> 368 CrĂ©ez un dossier 369 <literal> 370 C:\rst2dn 371 </literal> 372 (par exemple). 373 </paragraph> 374 </list_item> 375 <list_item> 376 <paragraph> 377 Copiez 378 <literal> 379 docutils-xml.py 380 </literal> 381 dans ce dossier. 382 </paragraph> 383 </list_item> 384 <list_item> 385 <paragraph> 386 Toujours dans ce dossier, faites un script Batch nommĂ©, par 387 exemple, 388 <literal> 389 rst2dn.bat 390 </literal> 391 contenant la ligne suivante 392 </paragraph> 393 <literal_block xml:space="preserve"> 394 python docutils-xml.py %* 395 </literal_block> 396 </list_item> 397 <list_item> 398 <paragraph> 399 Ajouter le dossier 400 <literal> 401 C:\rst2dn 402 </literal> 403 Ă| la variable PATH en insĂ©rant 404 la ligne suivante dans 405 <literal> 406 C:\autoexec.bat 407 </literal> 408 : 409 </paragraph> 410 <literal_block xml:space="preserve"> 411 set PATH=%PATH%;C:\rst2dn 412 </literal_block> 413 </list_item> 414 </enumerated_list> 415 </list_item> 416 </bullet_list> 417 </list_item> 418 <list_item> 419 <paragraph> 420 un processeur XSLT 421 </paragraph> 422 <paragraph> 423 Il existe toute une sĂ©rie de processeurs XSLT. Je recommande 424 425 <reference refuri="http://xmlsoft.org"> 426 Xsltproc 427 </reference> 428 . Il est fiable et (beaucoup) plus rapide que les autres. Il 429 est nĂ©anmoins possible d'utiliser 430 <reference refuri="http://saxon.sf.net"> 431 Saxon 432 </reference> 433 , 434 <reference refuri="http://xml.apache.org"> 435 Xalan 436 </reference> 437 , etc. 438 </paragraph> 439 </list_item> 440 </bullet_list> 441 <target id="xsltproc" name="xsltproc" refuri="http://xmlsoft.org"/> 442 <target id="saxon" name="saxon" refuri="http://saxon.sf.net"/> 443 <target id="xalan" name="xalan" refuri="http://xml.apache.org"/> 444 </section> 445 <section id="installation-de-dn2dbk" name="installation de dn2dbk"> 446 <title> 447 Installation de dn2dbk 448 </title> 449 <paragraph> 450 Placez la feuille 451 <literal> 452 dn2dbk.xsl 453 </literal> 454 oĂč vous voulez et dĂ©finissez une 455 variable d'environnement qui pointe dessus. 456 </paragraph> 457 <bullet_list bullet="-"> 458 <list_item> 459 <paragraph> 460 Sous GNU/Linux, je place habituellement mes feuilles XSL dans mon 461 rĂ©pertoire perso : 462 <literal> 463 ~/xsl 464 </literal> 465 . J'ajoute donc la ligne suivante dans 466 467 <literal> 468 ~/bashrc 469 </literal> 470 : 471 </paragraph> 472 <literal_block xml:space="preserve"> 473 export DN2DBK=~/xsl/dnxml2dbk.xsl 474 </literal_block> 475 </list_item> 476 <list_item> 477 <paragraph> 478 Sous Windows, ajoutez la ligne suivante dans 479 <literal> 480 C:\autoexec.bat 481 </literal> 482 : 483 </paragraph> 484 <literal_block xml:space="preserve"> 485 set DN2DBK = C:\xsl\dnxml2dbk.xsl 486 </literal_block> 487 </list_item> 488 </bullet_list> 489 </section> 490 </section> 491 <section id="utilisation" name="utilisation"> 492 <title> 493 Utilisation 494 </title> 495 <enumerated_list enumtype="arabic" prefix="" suffix=")"> 496 <list_item> 497 <paragraph> 498 Conversion RST vers DN-XML. 499 </paragraph> 500 <bullet_list bullet="-"> 501 <list_item> 502 <paragraph> 503 Sous GNU/Linux, la syntaxe est: 504 </paragraph> 505 <literal_block xml:space="preserve"> 506 docutils-xml.py myrst.txt myrst-dn.xml 507 </literal_block> 508 </list_item> 509 <list_item> 510 <paragraph> 511 Sous Windows: 512 </paragraph> 513 <literal_block xml:space="preserve"> 514 rst2dnxml.bat myrst.txt myrst-dn.xml 515 </literal_block> 516 </list_item> 517 </bullet_list> 518 </list_item> 519 <list_item> 520 <paragraph> 521 Conversion DN-XML vers Docbook-XML avec Xsltproc. 522 </paragraph> 523 <paragraph> 524 Je pars ici du principe que l'emplacement de la feuille XSLT 525 526 <literal> 527 dn2dbk.xsl 528 </literal> 529 a Ă©tĂ© rĂ©fĂ©rencĂ© dans la variable d'environnement 530 531 <literal> 532 DN2DBK 533 </literal> 534 . Sinon, remplacez 535 <literal> 536 $DN2DBK 537 </literal> 538 ou 539 <literal> 540 %DN2DBK% 541 </literal> 542 par le 543 chemin vers 544 <literal> 545 dn2dbk.xsl 546 </literal> 547 . 548 </paragraph> 549 <bullet_list bullet="-"> 550 <list_item> 551 <paragraph> 552 Sous GNU/Linux, la syntaxe est 553 </paragraph> 554 <literal_block xml:space="preserve"> 555 xsltproc -o myrst-dbk.xml $DN2DBK myrst-dn.xml 556 </literal_block> 557 </list_item> 558 <list_item> 559 <paragraph> 560 Sous Windows 561 </paragraph> 562 <literal_block xml:space="preserve"> 563 xsltproc -o myrst-dbk.xml %DN2DBK% myrst-dn.xml 564 </literal_block> 565 </list_item> 566 </bullet_list> 567 </list_item> 568 </enumerated_list> 569 </section> 570 <section id="r-f-rence-de-la-conversion" name="rĂ©fĂ©rence de la conversion"> 571 <title> 572 RĂ©fĂ©rence de la conversion 573 </title> 574 <paragraph> 575 Voir 576 <reference refuri="ref/index.htm"> 577 Reference 578 </reference> 579 </paragraph> 580 <target id="reference" name="reference" refuri="ref/index.htm"/> 581 </section> 582 <section id="aper-u-des-divers-formats-de-ce-document" name="aperçu des divers formats de ce document"> 583 <title> 584 Aperçu des divers formats de ce document 585 </title> 586 <paragraph> 587 Ce document a Ă©tĂ© rĂ©digĂ© au format RST avec 588 <reference refuri="http://www.vim.or"> 589 GVim 590 </reference> 591 puis converti au 592 format Docbook avec 593 <literal> 594 dn2dbk.xsl 595 </literal> 596 . 597 </paragraph> 598 <paragraph> 599 La version HTML a Ă©tĂ© rĂ©alisĂ©e avec les 600 <reference refuri="http://docbook.sourceforge.net/projects/xsl/index.html"> 601 feuilles XSLT de Norman Walsh 602 </reference> 603 Ă| 604 partir du document Docbook. 605 </paragraph> 606 <target id="feuilles-xslt-de-norman-walsh" name="feuilles xslt de norman walsh" refuri="http://docbook.sourceforge.net/projects/xsl/index.html"/> 607 <target id="gvim" name="gvim" refuri="http://www.vim.or"/> 608 <paragraph> 609 Afin de faciliter la consultation des sources, le code des fichier XML 610 est prĂ©sentĂ© au format HTML (la conversion Ă| Ă©tĂ© rĂ©alisĂ©e avec Vim). 611 </paragraph> 612 <paragraph> 613 Vous trouverez les sources rĂ©elles dans l'archive 614 <reference refuri="dn2dbk-0.3.tar.gz"> 615 dn2dbk-0.3.tar.gz 616 </reference> 617 </paragraph> 618 <bullet_list bullet="-"> 619 <list_item> 620 <paragraph> 621 Format RST : 622 <reference refuri="rst2dbk.txt"> 623 rst2dbk.txt 624 </reference> 625 (la source rĂ©elle du document) 626 </paragraph> 627 </list_item> 628 <list_item> 629 <paragraph> 630 Code du fichier DN-XML : 631 <reference refuri="dn-rst2dbk.xml.html"> 632 dn-rst2dbk.xml.html 633 </reference> 634 </paragraph> 635 </list_item> 636 <list_item> 637 <paragraph> 638 Code du fichier Docbook-XML : 639 <reference refuri="dbk-rst2dbk.xml.html"> 640 dbk-rst2dbk.xml.html 641 </reference> 642 </paragraph> 643 </list_item> 644 </bullet_list> 645 <target id="rst2dbk-txt" name="rst2dbk.txt" refuri="rst2dbk.txt"/> 646 <target id="dn-rst2dbk-xml-html" name="dn-rst2dbk.xml.html" refuri="dn-rst2dbk.xml.html"/> 647 <target id="dbk-rst2dbk-xml-html" name="dbk-rst2dbk.xml.html" refuri="dbk-rst2dbk.xml.html"/> 648 <comment xml:space="preserve"> 649 Liens 650 ===== 651 </comment> 652 <target id="python" name="python" refuri="http://www.python.org"/> 653 <target id="docutils" name="docutils" refuri="http://docutils.sf.net"/> 654 <target id="dnxml2dbk-xsl" name="dnxml2dbk.xsl" refuri="http://www.chez.com/ebellot/rest"/> 655 </section> 656 </document>