         Conversion de documents DocBook XML/SGML avec OpenJade

  Version franaise de DocBook XML/SGML Processing Using OpenJade

  Saqib Ali

   <saqib CHEZ seagate POINT com>

   Traduction franaise: Guillaume Audirac

   <guillaume POINT audirac CHEZ netpratique POINT fr>

   Relecture de la version franaise: Encolpe Degoute

   <encolpe CHEZ colpi POINT info>

   Prparation de la publication de la v.f.: Jean-Philippe Gurard

   <jean TIRET philippe POINT guerard CHEZ corbeaunoir POINT org>

   Version : 2.2.8.fr.1.0

   2003-08-29

   +----------------------------------------------------------------+
   | Historique des versions                                        |
   |----------------------------------------------------------------|
   | Version 2.2.8.fr.1.0       | 2003-08-29      | GA, ED, JPG     |
   |----------------------------------------------------------------|
   | Traduction de la version 2.2.8 de DocBook XML/SGML Processing  |
   | Using OpenJade. Ajout du point 4  la section  Installation   |
   | du DSL du TLDP .                                              |
   |----------------------------------------------------------------|
   | Version 2.2.8              | 2003-07-16      | ES              |
   |----------------------------------------------------------------|
   | Ajout d'information sur la mise  jour des JRE pour Cocoon.    |
   | (Added info about keeping JREs up-to-date for Cocoon)          |
   |----------------------------------------------------------------|
   | Version 2.2.7              | 2003-07-09      | ES              |
   |----------------------------------------------------------------|
   | Restitution du lien rompu et d'autres fichiers spcifiques sur |
   | le XSL du TLDP. (Fixed broken links to LDP XSL and other LDP   |
   | XSL specific filenames.)                                       |
   |----------------------------------------------------------------|
   | Version 2.2.6              | 2003-06-16      | SA              |
   |----------------------------------------------------------------|
   | Vrification de l'instruction sur DocBook XSL 1.57. (Verified  |
   | the instruction against docbook XSL 1.57.)                     |
   |----------------------------------------------------------------|
   | Version 2.2.5              | 2003-05-16      | SA              |
   |----------------------------------------------------------------|
   | Restitution des liens rompus dans la partie Informations       |
   | supplmentaires. (Fixed the broken links in the external       |
   | resources section.)                                            |
   |----------------------------------------------------------------|
   | Version 2.2.4              | 2003-04-20      | SA              |
   |----------------------------------------------------------------|
   | Mise  jour des liens vers le nouveau site de dmonstration.   |
   | Ajout de nouveaux liens dans la partie Informations            |
   | supplmentaires. (Updated links to the new Demo Site. Added    |
   | new links to the resources section.)                           |
   |----------------------------------------------------------------|
   | Version 2.2.3              | 2002-11-22      | SA              |
   |----------------------------------------------------------------|
   | Ajout de suggestions d'utilisateurs. Ajout de nouveaux liens   |
   | dans la partie Informations supplmentaires. (Added the        |
   | suggestion made by users. Added new links to the resources     |
   | section.)                                                      |
   |----------------------------------------------------------------|
   | Version 2.2.2              | 2002-10-09      | AS              |
   |----------------------------------------------------------------|
   | Cette mise  jour corrige quelques autres erreurs              |
   | typographiques, supprime quelques espaces qui dfiguraient le  |
   | rendu HTML. (This update fixes a few more typos, removes a     |
   | couple of spaces that make the HTML rendering look odd.)       |
   |----------------------------------------------------------------|
   | Version 2.2.1              | 2002-10-09      | SA              |
   |----------------------------------------------------------------|
   | Correction de l'adresse URL vers le fichier d'exemples. (Fixed |
   | the URL to the Sample Files.)                                  |
   |----------------------------------------------------------------|
   | Version 2.2                | 2002-09-29      | AS              |
   |----------------------------------------------------------------|
   | Corrections mineures dans la partie sur Cocoon. (Minor         |
   | corrections to the Cocoon section.)                            |
   |----------------------------------------------------------------|
   | Version 2.1                | 2002-09-15      | SA              |
   |----------------------------------------------------------------|
   | Corrections mineures dans la partie sur Cocoon. (Minor         |
   | corrections to the Cocoon section.)                            |
   |----------------------------------------------------------------|
   | Version 2.0                | 2002-09-10      | SA              |
   |----------------------------------------------------------------|
   | Ajout de la partie sur la mise  disposition de contenus       |
   | DocBook XML 4.1.2  l'aide de Tomcat + Cocoon. (Added the      |
   | section on serving DocBook XML 4.1.2 content using Tomcat +    |
   | Cocoon.)                                                       |
   |----------------------------------------------------------------|
   | Version 1.5                | 2002-08-11      | SA              |
   |----------------------------------------------------------------|
   | Ajout de la partie sur XML et du fichier d'exemples XML.       |
   | (Added the XML section and the sample XML file.)               |
   |----------------------------------------------------------------|
   | Version 1.4                | 2002-08-08      | SA              |
   |----------------------------------------------------------------|
   | Nombreuses et prcieuses modifications et corrections          |
   | suggres par Lloyd D. Budd. Merci Lloyd :) (Many valuable     |
   | modifications/corrections suggested by Lloyd D. Budd. Thanks   |
   | Lloyd. :))                                                     |
   |----------------------------------------------------------------|
   | Version 1.3                | 2002-08-02      | SA              |
   |----------------------------------------------------------------|
   | Ajout de la partie Informations supplmentaires. (Added the    |
   | "Additional Resources" section.)                               |
   |----------------------------------------------------------------|
   | Version 1.2                | 2002-07-23      | SA              |
   |----------------------------------------------------------------|
   | Ajout de la partie sur la conversion HTML -> PDF en utilisant  |
   | HTMLDOC. Merci  Luc de Louw pour cette suggestion. (Added the |
   | section on converting HTML -> PDF using HTMLDOC. Thanks to Luc |
   | De Louw for the suggestion.)                                   |
   |----------------------------------------------------------------|
   | Version 1.1                | 2002-07-19      | KET             |
   |----------------------------------------------------------------|
   | Correction de fautes grammaticales et d'numrations. (Fixed   |
   | grammatical errors, numbered processes.)                       |
   |----------------------------------------------------------------|
   | Version 1.0                | 2002-06-29      | SA              |
   |----------------------------------------------------------------|
   | Version publique initiale. (Initial public release.)           |
   +----------------------------------------------------------------+

   Rsum

   Ce guide pratique (howto) vous explique comment configurer
   OpenJade pour transformer des documents XML et SGML.

   -------------------------------------------------------------------

   Table des matires

   1. Introduction

                1.1. Droits d'utilisation

                1.2. Copyright et licence

                1.3. Remerciements

                1.4. Qu'est-ce que DocBook ?

                1.5. Qu'est ce qu'un DSSSL ?

                1.6. De quoi avons-nous besoin ?

                1.7. Conditions

   2. Les indispensables

                2.1. Pralable

                2.2. OpenJade

                2.3. Les DTD DocBook

                2.4. Les entits ISO

                2.5. Le DSSSL de Norman Walsh

                2.6. Feuilles de style DSL personnalises par le TLDP

                2.7. HTMLDOC (optionnel)

                2.8. Le XSL de Norman Walsh (optionnel)

                2.9. Le XSL personnalis du TLDP (optionnel)

   3. Installation des outils de conversion -- OpenJade

                3.1. Installation d'OpenJade

                3.2. Installation du DSSSL de Norman Walsh

                3.3. Installation des DTD DocBook

                3.4. Installation des entits ISO

                3.5. Installation du DSL du TLDP

                3.6. Installation de HTMLDOC

   4. Utilisation d'OpenJade

                4.1. Traitement du SGML

                4.2. Traitement du XML

                4.3. HTML vers PDF (optionnel)

   5. Publier DocBook 4.1.2 XML

                5.1. Tomcat + Cocoon

                5.2. Installation du XSL de Norman Walsh

                5.3. Installation du XSL du TLDP

                5.4. Configuration de sitemap.xmap

                5.5. Accs  un contenu DocBook 4.1.2 XML dans un
                navigateur Internet

   6. Informations supplmentaires

                6.1. Groupes de nouvelles

                6.2. Listes de diffusion

                6.3. IRC

                6.4. Sites Internet

                6.5. Applications de rdaction et de modelage du XML

1. Introduction

   Quelques acronymes :

    1. SGML -- Langage normalis de balisage gnralis (Standard
       Generalized Markup Language)

    2. XML -- Langage de balisage extensible (Extensible Markup
       Language)

    3. RTF -- Format de texte avec enrichissements (Rich Text Format)

    4. HTML -- Langage de balisage hypertexte (HyperText Markup
       Language)

    5. PDF -- Format de document portable (Portable Document Format)

   L'objectif de ce document est de configurer OpenJade pour
   convertir des documents DocBook 3.2 et 4.2 SGML et XML vers les
   formats HTML, RTF et PDF.

  1.1. Droits d'utilisation

   [1][Note] Note                           
             Le texte ci-dessous est la version franaise de la
             licence de ce document. Seule la version originale de
             cette licence, prsente dans la section suivante, fait
             foi.                           

   Copyright  2001, Saqib Ali.

   Copyright  2003, Guillaume Audirac, Encolpe Degoute et
   Jean-Philippe Gurard pour la version franaise.

   La version originale de ce document a t ralise par Saqib Ali
   en 2001.

   Vous avez le droit de copier, distribuer et modifier la version
   originale de ce document selon les termes de la licence de
   documentation libre GNU (GFDL)
   [http://www.gnu.org/copyleft/fdl.html] version 1.1 ou ultrieures,
   telle que publie par la Free Software Fondation (FSF); sans
   section invariante, sans texte de premire de couverture ni texte
   de quatrime de couverture. Une copie de la licence est disponible
    http://www.gnu.org/copyleft/fdl.html
   [http://www.gnu.org/copyleft/fdl.html].

   La version franaise de ce document a t ralise par Guillaume
   Audirac et Encolpe Degoute. La version franaise de ce guide
   pratique est publie en accord avec les termes de la licence de
   documentation libre GNU (GFDL)
   [http://www.gnu.org/copyleft/fdl.html]; sans section invariante,
   sans texte de premire de couverture ni texte de quatrime de
   couverture. Une copie de la licence est disponible 
   http://www.gnu.org/copyleft/fdl.html
   [http://www.gnu.org/copyleft/fdl.html].

   Une version franaise non-officielle de cette licence est
   disponible  http://cesarx.free.fr/gfdlf.html
   [http://cesarx.free.fr/gfdlf.html].

  1.2. Copyright et licence

   [2][Note] Note                           
             Le texte ci-dessous est la licence de ce document. Ce
             texte fait foi. Il est compos de la licence en anglais
             du document original, suivi de la licence en franais de
             sa traduction.                 

   Copyright  2001, Saqib Ali.

   Copyright  2003, Guillaume Audirac, Encolpe Degoute et
   Jean-Philippe Gurard pour la version franaise.

   Permission is granted to copy, distribute and/or modify this
   document under the terms of the GNU Free Documentation License
   [http://www.gnu.org/copyleft/fdl.html], Version 1.1 or any later
   version published by the Free Software Foundation; with no
   Invariant Sections, with no Front-Cover Texts, and with no
   Back-Cover Texts. A copy of the license is available at
   http://www.gnu.org/copyleft/fdl.html
   [http://www.gnu.org/copyleft/fdl.html].

   La version franaise de ce document a t ralise par Guillaume
   Audirac et Encolpe Degoute. La version franaise de ce guide
   pratique est publie en accord avec les termes de la licence de
   documentation libre GNU (GFDL)
   [http://www.gnu.org/copyleft/fdl.html]; sans section invariante,
   sans texte de premire de couverture ni texte de quatrime de
   couverture. Une copie de la licence est disponible 
   http://www.gnu.org/copyleft/fdl.html
   [http://www.gnu.org/copyleft/fdl.html].

  1.3. Remerciements

   Toute la gloire revient  Allah, le Matre des Mondes. Tout le
   mrite revient  Allah. La moindre erreur dans ce document est de
   ma propre faute.

   De plus, j'aimerais remercier les personnes suivantes pour leurs
   prcieuses contributions  ce document :

    1. Eric Safern <esafern CHEZ lrn POINT com> pour les mises  jour
       concernant Cocoon et le JRE. http://www.timebytes.com/
       [http://www.timebytes.com/].

    2. Greg Ferguson <gferg CHEZ hoop POINT timonium POINT sgi POINT
       com> pour ses judicieuses suggestions et astuces sur la liste
       de diffusion de DocBook.

    3. Kristin Thomas <kristint CHEZ us POINT ibm POINT com> pour la
       relecture initiale de la version originale de ce document.

    4. Luc de Louw <luc CHEZ delouw POINT ch> pour avoir suggrer la
       partie sur HTMLDOC (PDF -> HTML).

    5. Lloyd D. Budd <ldp CHEZ foolswisdom POINT org> pour ses
       propositions d'amlioration de la plupart des parties de ce
       document.

    6. Andrew Shugg <andrew CHEZ neep POINT com POINT au> pour la
       correction des erreurs de la version 2.0 de ce document. Neep
       Consulting [http://www.neep.com.au/].

  1.4. Qu'est-ce que DocBook ?

   DocBook, c'est une dfinition de type de document (Document Type
   Definition ou DTD). DocBook dcrit les types de structures et de
   formats  employer dans les documents techniques. Il est
   couramment utilis du fait de sa simplicit et de son
   exhaustivit.

   Une DTD dfinit la syntaxe d'un document -- c'est principalement
   un livre de rgles qui dcrit un ensemble de balises et
   d'attributs, qui seront utiliss pour dcrire des types
   spcifiques de contenus. Ainsi, DocBook est un livre de rgles
   utilis pour crire des documents. Chaque balise utilise dans la
   rdaction du document, doit tre dfinie spcifiquement et
   formellement dans la DTD.

  1.5. Qu'est ce qu'un DSSSL ?

   C'est un langage de symboles et de spcifications de style de
   document (Document Style Semantics and Specification Language ou
   DSSSL). Il dfinit comment convertir un format SGML (ou XML) vers
   un format affichable et lisible par l'tre humain, comme HTML, RTF
   et PDF.

  1.6. De quoi avons-nous besoin ?

   Voici les outils ncessaires  la configuration d'OpenJade pour
   convertir le SGML et le XML :

     o OpenJade

     o Les DTD DocBook

     o Les entits ISO

     o Le DSSSL de Norman Walsh

     o Le DSL du TLDP

     o HTMLDOC (optionnel)

     o Le XSL de Norman Walsh (optionnel)

     o Le XSL du TLDP (optionnel)

   [3][Note] Note                               
             Tous ces paquets sont libres et disponibles en
             tlchargement sur Internet. Le chapitre suivant
             explique comment les tlcharger.  

  1.7. Conditions

   Ce document considre que ce qui suit est dj install sur votre
   systme :

     o gzip -- disponible  http://www.gnu.org/directory/
       [http://www.gnu.org/directory/].

     o gcc et GNU make -- disponible  http://www.gnu.org/directory/
       [http://www.gnu.org/directory/].

     o unzip -- disponible  http://www.info-zip.org/pub/infozip/
       [http://www.info-zip.org/pub/infozip/].

     o Les utilitaires Unix classiques -- tar, mkdir, mv ...

2. Les indispensables

   Vous devrez tlcharger et compiler un seul paquet (OpenJade). Ce
   guide pratique expliquera l'tape de compilation, mais il serait
   prfrable que vous soyez familier des installations de code
   source.

   La plupart des paquets ncessaires sont situs sur le site
   Internet du projet de documentation Linux (The Linux Documentation
   Project ou TLDP)
   [http://www.tldp.org/authors/index.html#resources].

  2.1. Pralable

   Crez un dossier /tmp/downloads. Nous l'utiliserons pour stocker
   les codes sources tlchargs.

  2.2. OpenJade

   OpenJade sera utilis pour traiter les documents DocBook. OpenJade
   peut tre tlcharg  http://openjade.sourceforge.net/
   [http://openjade.sourceforge.net/].

   Lors de la rdaction de ce document, OpenJade version 1.3.1 tait
   disponible. Tlchargez le fichier openjade-1.3.x.tar.gz.

  2.3. Les DTD DocBook

   Toutes les DTD DocBook sont disponibles sur le site Internet de
   The Linux Documentation Project 
   http://www.tldp.org/authors/index.html#resources
   [http://www.tldp.org/authors/index.html#resources].

   Veuillez tlcharger DocBook SGML v4.1
   [http://www.tldp.org/authors/tools/docbk41.zip], DocBook SGML v3.1
   [http://www.tldp.org/authors/tools/docbk31.zip], et DocBook XML
   v4.1.2 [http://www.tldp.org/authors/tools/docbkx412.zip].

   [4][Note] Note                              
             Veuillez tlcharger toutes les archives au format
             compress zip.                    

  2.4. Les entits ISO

   Le projet de documentation Linux (The Linux Documentation Project
   [http://www.tldp.org]) a empaquet toutes les entits en un seul
   et gros fichier tar, et l'a plac 
   http://www.tldp.org/authors/tools/entities.tar.gz
   [http://www.tldp.org/authors/tools/entities.tar.gz] pour le
   confort des utilisateurs. Remercions le TLDP pour a.

  2.5. Le DSSSL de Norman Walsh

   Le DSSSL de Norman Walsh peut tre tlcharg sur le site Internet
   du projet DocBook 
   http://sourceforge.net/project/showfiles.php?group_id=21935
   [http://sourceforge.net/project/showfiles.php?group_id=21935].

   Lors de la rdaction de ce document, docbook-dsssl-1.76 tait
   disponible.

  2.6. Feuilles de style DSL personnalises par le TLDP

   Le DSL du TLDP est une feuille de style personnalise et utilise
   par The Linux Documentation Project (TLDP) [http://www.tldp.org].
   C'est une prolongation du DSSSL de Norman Walsh. Il y ajoute
   plusieurs choses comme un arrire-plan ou une table des matires.
   Il peut tre tlcharg 
   http://www.tldp.org/authors/tools/ldp.dsl
   [http://www.tldp.org/authors/tools/ldp.dsl].

   Le fichier ldp.dsl ncessite le DSSSL de Norman Walsh.

  2.7. HTMLDOC (optionnel)

   HTMLDOC peut tre utilis pour convertir le HTML en PDF. Si vous
   souhaitez crer des documents PDF, tlchargez HTMLDOC 
   http://www.easysw.com/htmldoc/software.php
   [http://www.easysw.com/htmldoc/software.php].

  2.8. Le XSL de Norman Walsh (optionnel)

   Ceci n'est pas indispensable. Mais si vous dsirez reconnatre des
   contenus DocBook 4.1.2 XML en utilisant Tomcat + Cocoon, vous
   aurez besoin des feuilles de style XML de Norman Walsh.

   Les feuilles de style sont tlchargeables 
   http://sourceforge.net/projects/docbook/
   [http://sourceforge.net/projects/docbook/].

   Tlchargez le paquet nomm docbook-xsl.

   [5][Note] Note                           
             Rcemment, docbook-xsl version 1.57.0 a t rendu
             publique. Ce document est valide avec la dernire
             version, et des changements adquats ont t effectus.
             Si vous rencontrez encore des erreurs, merci de m'crire
              l'adresse <saqib CHEZ seagate POINT com>

  2.9. Le XSL personnalis du TLDP (optionnel)

   Tlchargez galement le XSL personnalis du TLDP 
   http://my.core.com/~dhorton/docbook/tldp-xsl/
   [http://my.core.com/~dhorton/docbook/tldp-xsl/].

3. Installation des outils de conversion -- OpenJade

   Dans cette section, nous installerons tous les outils dans les
   dossiers appropris. Tous vont dans /usr/local/dbtools/. Crez ce
   dossier  l'aide de la commande suivante :

 # mkdir /usr/local/dbtools

  3.1. Installation d'OpenJade

   Cette procdure est la partie la plus facile, mais aussi la plus
   longue. Gardez  l'esprit que la compilation d'OpenJade demande du
   temps. Pour installer OpenJade, ralisez les oprations suivantes
   :

    1. Positionnez-vous dans le dossier /tmp/downloads.

 # cd /tmp/downloads

    2. Dcompressez le fichier.

 # gzip -d openjade-1.3.x.tar.gz

    3. Dpaquetez le fichier.

 # tar -xvf openjade-1.3.x.tar

    4. Dplacez-vous dans le dossier openjade-1.3

 # cd openjade-1.3.x

    5. Excutez la commande ./configure.

 # ./configure --prefix=/usr/local/dbtools/openjade

    6. Excutez la commande make.

 # make

    7. Excutez la commande make install. Ds maintenant, les
       fichiers binaires d'OpenJade seront installs sous
       /usr/local/dbtools/openjade.

 # make install

    8. Copiez le dossier dsssl de /tmp/downloads/openjade-1.3.x vers
       /usr/local/dbtools/openjade.

 # cp -dpR dsssl /usr/local/dbtools/openjade/

  3.2. Installation du DSSSL de Norman Walsh

   Durant cette tape, nous installerons le DSSSL de Norman Walsh
   dans un endroit appropri. Le DSSSL n'a pas besoin d'tre compil.

    1. Positionnez-vous dans le dossier /tmp/downloads.

 # cd /tmp/downloads

    2. Dcompressez le fichier.

 # gzip -d docbook-dsssl-1.76.tar.gz

    3. Dpaquetez le fichier.

 # tar -xvf docbook-dsssl-1.76.tar

    4. Dplacez-vous dans le dossier
       /usr/local/dbtools/docbook-dsssl.

 # mv docbook-dsssl-1.76 /usr/local/dbtools/docbook-dsssl

  3.3. Installation des DTD DocBook

   Dans cette section, nous installerons les DTD DocBook.

    1. Positionnez-vous dans le dossier /usr/local/dbtools.

 # cd /usr/local/dbtools

    2. Crez trois nouveaux dossiers, nomms dtd3.1, dtd4.1, et
       dtd4.1.2.

 # mkdir dtd3.1
 # mkdir dtd4.1
 # mkdir dtd4.1.2

    3. Dplacez-vous dans le dossier dtd3.1.

 # cd dtd3.1

    4. Dcompressez le fichier DocBook SGML v3.1 dans ce dossier.

 # unzip /tmp/downloads/docbk31.zip

    5. Dplacez-vous dans le dossier dtd4.1.

 # cd ../dtd4.1

    6. Dcompressez le fichier DocBook SGML v4.1 dans ce dossier.

 # unzip /tmp/downloads/docbk41.zip

    7. Dplacez-vous dans le dossier dtd4.1.2.

 # cd ../dtd4.1.2

    8. Dcompressez le fichier DocBook XML v4.1.2 dans ce dossier.

 # unzip /tmp/downloads/docbk412.zip

  3.4. Installation des entits ISO

   Dans cette section, nous installerons les entits ISO que nous
   avons tlcharges sur le site Internet du TLDP.

   Tout d'abord, nous installons les entits ISO pour la DTD 3.1
   SGML.

    1. Positionnez-vous dans le dossier /usr/local/dbtools/dtd3.1.

 # cd /usr/local/dbtools/dtd3.1

    2. Copiez ici le fichier /tmp/download/entities.tar.gz.

 # cp /tmp/download/entities.tar.gz .

    3. Dcompressez le fichier.

 # gzip -d entities.tar.gz

    4. Dpaquetez le fichier.

 # tar -xvf entities.tar

   Ensuite, nous installons les entits ISO pour la DTD 4.1 SGML.

    1. Positionnez-vous dans le dossier /usr/local/dbtools/dtd4.1.

 # cd /usr/local/dbtools/dtd4.1

    2. Copiez ici le fichier /tmp/download/entities.tar.gz.

 # cp /tmp/download/entities.tar.gz .

    3. Dcompressez le fichier.

 # gzip -d entities.tar.gz

    4. Dpaquetez le fichier.

 # tar -xvf entities.tar

  3.5. Installation du DSL du TLDP

   Enfin, nous installons la feuille de style personnalise du TLDP.

    1. Positionnez-vous dans le dossier /tmp/download.

 # cd /tmp/download

    2. Copiez le fichier ldp.dsl  l'emplacement
       /usr/local/dbtools/docbook-dsssl/print.

 # cp ldp.dsl /usr/local/dbtools/docbook-dsssl/print

    3. Copiez le fichier ldp.dsl  l'emplacement
       /usr/local/dbtools/docbook-dsssl/html.

 # cp ldp.dsl /usr/local/dbtools/docbook-dsssl/html

    4. Le contenu du fichier ldp.dsl doit tre modifi pour reflter
       le chemin absolu du fichier docbook.dsl. Voici la zone
       originale du fichier qui doit tre adapte :

 <![%html;[
 <!ENTITY % print "IGNORE">
 <!ENTITY docbook.dsl PUBLIC
          "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN"
          CDATA dsssl>
 ]]>
 <!ENTITY % print "INCLUDE">
 <![%print;[
 <!ENTITY docbook.dsl PUBLIC
          "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN"
          CDATA dsssl>
 ]]>    

       ditez le fichier ldp.dsl situ  l'emplacement
       /usr/local/dbtools/docbook-dsssl/print avec un diteur de
       texte.

 # emacs /usr/local/dbtools/docbook-dsssl/print/ldp.dsl

       Modifiez le contenu du fichier comme suit :

 <![%html;[
 <!ENTITY % print "IGNORE">
 <!ENTITY docbook.dsl SYSTEM
          "/usr/local/dbtools/docbook-dsssl/print/docbook.dsl"
          CDATA dsssl>
 ]]>
 <!ENTITY % print "INCLUDE">
 <![%print;[
 <!ENTITY docbook.dsl SYSTEM
          "/usr/local/dbtools/docbook-dsssl/print/docbook.dsl"
          CDATA dsssl>
 ]]>

       ditez le fichier ldp.dsl situ  l'emplacement
       /usr/local/dbtools/docbook-dsssl/html avec un diteur de
       texte.

 # emacs /usr/local/dbtools/docbook-dsssl/html/ldp.dsl

       Modifiez le contenu du fichier comme suit :

 <![%html;[
 <!ENTITY % print "IGNORE">
 <!ENTITY docbook.dsl SYSTEM
          "/usr/local/dbtools/docbook-dsssl/html/docbook.dsl"
          CDATA dsssl>
 ]]>
 <!ENTITY % print "INCLUDE">
 <![%print;[
 <!ENTITY docbook.dsl SYSTEM
          "/usr/local/dbtools/docbook-dsssl/html/docbook.dsl"
          CDATA dsssl>
 ]]>

  3.6. Installation de HTMLDOC

   Cette tape est facultative. Elle est utile seulement si vous
   dsirez crer des documents PDF  partir de HTML.

   Retournez dans le dossier des tlchargements.

 # cd /tmp/download

   Dcompressez et dpaquetez le code source de HTMLDOC.

 # gzip -d htmldoc-1.8.xx-source.tar.gz
 # tar -xvf htmldoc-1.8.xx-source.tar
 # cd htmldoc-1.8.xx-1

   Excutez configure pour dfinir le chemin d'installation.

 # ./configure --prefix=/usr/local/dbtools/htmldoc
 # make

   Lors de la rdaction de ce document, HTMLDOC version 1.8.20-1
   tait disponible. Cette version connat un problme de fontes dans
   le fichier Makefile. Il devrait se plaindre  l'installation des
   fontes, parce qu'elles ne sont pas disponibles sur le systme.

   Voici l'erreur obtenue lorsque vous excuterez make install :

 # make install
 Making all in htmldoc...
 Making all in doc...
 Installing in fonts...
 Installing font files in /usr/local/dbtools/htmldoc/share/htmldoc/fonts...
 /bin/cp: cannot stat `ZapfChancery.afm': No such file or directory
 /bin/cp: cannot stat `ZapfChancery.pfa': No such file or directory
 /bin/cp: cannot stat `ZapfDingbats.afm': No such file or directory
 /bin/cp: cannot stat `ZapfDingbats.pfa': No such file or directory
 make[1]: *** [install] Error 1

   Pour corriger ce problme d'installation, ditez le fichier
   fonts/Makefile et mettez en commentaires les lignes rfrences
   aux fontes ZapfChancery et ZapfDingbats.

   Ensuite, excutez l'installation :

 # make install
 Making all in htmldoc...
 Making all in doc...
 Installing in fonts...
 Installing font files in /usr/local/dbtools/htmldoc/share/htmldoc/fonts...
 Installing in data...
 Installing in doc...
 Installing in htmldoc...

4. Utilisation d'OpenJade

   Dans cette section, nous utiliserons OpenJade pour convertir des
   documents DocBook SGML/XML en HTML, RTF, et PDF.

  4.1. Traitement du SGML

    4.1.1. Dfinition de la variable environnementale SGML_CATALOG_FILES
    pour le SGML

   La variable SGML_CATALOG_FILES doit tre dfinie pour pointer sur
   les fichiers catalog appropris. Pour dfinir la variable,
   utilisez la commande suivante pour le Bourne shell :

 # export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:\
 > /usr/local/dbtools/dtd3.1/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog

   Pour le C shell, utilisez cette commande :

 # setenv SGML_CATALOG_FILES /usr/local/dbtools/openjade/dsssl/catalog
 # setenv SGML_CATALOG_FILES "$SGML_CATALOG_FILES":/usr/local/dbtools/dtd3.1/docbook.cat
 # setenv SGML_CATALOG_FILES "$SGML_CATALOG_FILES":/usr/local/dbtools/docbook-dsssl/catalog

    4.1.2. SGML vers HTML

   Pour convertir du SGML en HTML, utilisez la commande suivante :

 # /usr/local/dbtools/openjade/bin/openjade -t sgml \
 > -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html \
 > DocBook-OpenJade-SGML-XML-HOWTO.sgml

   Pour crer un document d'une pice (tout dans un seul fichier) :

 # /usr/local/dbtools/openjade/bin/openjade -V nochunks -t sgml \
 > -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html \
 > DocBook-OpenJade-SGML-XML-HOWTO.sgml

    4.1.3. SGML vers RTF

   Pour convertir du SGML en RTF, utilisez la commande suivante :

 # /usr/local/dbtools/openjade/bin/openjade -t rtf \
 > -d /usr/local/dbtools/docbook-dsssl/print/ldp.dsl#print \
 > DocBook-OpenJade-SGML-XML-HOWTO.sgml

  4.2. Traitement du XML

   Vous pouvez tlcharger un exemple de fichier DocBook 4.1.2 XML 
   http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml
   [http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml]

    4.2.1. Dfinition de la variable environnementale SGML_CATALOG_FILES
    pour le XML

   La variable SGML_CATALOG_FILES doit tre dfinie pour pointer sur
   les fichiers catalog appropris. Pour dfinir la variable,
   utilisez la commande suivante pour le Bourne shell :

 # export SGML_CATALOG_FILES=/usr/local/dbtools/openjade/dsssl/catalog:\
 > /usr/local/dbtools/dtd4.1.2/docbook.cat:/usr/local/dbtools/docbook-dsssl/catalog

   Pour le C shell, utilisez cette commande :

 # setenv SGML_CATALOG_FILES /usr/local/dbtools/openjade/dsssl/catalog
 # setenv SGML_CATALOG_FILES "$SGML_CATALOG_FILES":/usr/local/dbtools/dtd4.1.2/docbook.cat
 # setenv SGML_CATALOG_FILES "$SGML_CATALOG_FILES":/usr/local/dbtools/docbook-dsssl/catalog

    4.2.2. XML vers HTML

   Pour convertir du XML en HTML, utilisez la commande suivante :

 # /usr/local/dbtools/openjade/bin/openjade -t xml \
 > -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html\
 > /usr/local/dbtools/docbook-dsssl/dtds/decls/xml.dcl \
 > DocBook-OpenJade-SGML-XML-HOWTO.xml

    4.2.3. XML vers RTF

   Pour convertir du XML en RTF, utilisez la commande suivante :

 # /usr/local/dbtools/openjade/bin/openjade -t rtf \
 > -d /usr/local/dbtools/docbook-dsssl/print/ldp.dsl#print \
 > /usr/local/dbtools/docbook-dsssl/dtds/decls/xml.dcl \
 > DocBook-OpenJade-SGML-XML-HOWTO.xml

  4.3. HTML vers PDF (optionnel)

   Pour convertir du HTML en PDF, il faut utiliser HTMLDOC. Tout
   d'abord, crez un fichier HTML d'une pice  partir du SGML :

 # /usr/local/dbtools/openjade/bin/openjade -V nochunks -t sgml \
 > -d /usr/local/dbtools/docbook-dsssl/html/ldp.dsl#html \
 > DocBook-OpenJade-SGML-XML-HOWTO.sgml

   Maintenant, excutez HTMLDOC pour gnrer le PDF.

 # /usr/local/dbtools/htmldoc/bin/htmldoc -f outfile.pdf input.html

5. Publier DocBook 4.1.2 XML

   Il existe trois moyens de publier DocBook 4.1.2 XML sur un serveur
   Internet :

     o OpenJade en ligne de commande pr-interprte (command line
       pre-processed OpenJade), XSLT

     o Scripts -- PHP, Perl, Python

     o Serveur d'applications -- Tomcat + Cocoon

   La meilleure option est d'utiliser un serveur d'applications comme
   Cocoon.

   [6][Note] Cocoon en action                     
             Pour visualiser un exemple de serveur Internet publiant
             des contenus DocBook 4.1.2 XML avec Tomcat + Cocoon,
             visitez                              
             http://www.xml-dev.com:8080/cocoon/mount/docbook/
             [http://www.xml-dev.com:8080/cocoon/mount/docbook/].

   Dans cette section, nous verrons comment publier un contenu
   DocBook 4.1.2 XML avec Tomcat + Cocoon.

  5.1. Tomcat + Cocoon

   Tomcat est le contenant de mini-serveurs Java (Java Servlet
   Container). Pour plus d'informations, visitez
   http://jakarta.apache.org/tomcat/index.html
   [http://jakarta.apache.org/tomcat/index.html].

   Apache Cocoon est une structure de publication XML. Pour plus
   d'informations, visitez http://xml.apache.org/cocoon/index.html
   [http://xml.apache.org/cocoon/index.html].

   Ce guide pratique ne dtaillera pas la configuration de Tomcat +
   Cocoon, puisque c'est dj fait dans le document
   http://wiki.cocoondev.org/Wiki.jsp?page=CocoonCompetenceCenter
   [http://wiki.cocoondev.org/Wiki.jsp?page=CocoonCompetenceCenter].
   Cette configuration est simple et ne prendra pas plus de cinq
   minutes.

   Une fois Cocoon + Tomcat configurs et oprationnels, poursuivez
   aux sections suivantes pour publier des contenus DocBook 4.1.2
   XML.

   [7][Note] Avertissement important :                
             les spcialistes ont rencontr des problmes de
             compatibilit avec les feuilles de styles DocBook et
             certaines versions de l'analyseur syntaxique XML, Xalan.
             En fait, Xalan est l'analyseur syntaxique fournit avec
             le JRE de Sun, c'est donc ce que vous utilisez par
             dfaut.                                  

   En dernier lieu, assurez-vous d'utiliser la toute dernire version
   du JRE de Sun (1.4.2  la rdaction de ce document).

   De mme, mettez  jour l'analyseur Xalan avec sa dernire version.
   Pour ma part, la dernire version 1.4.2 du JRE de Sun est fournie
   avec Xalan 2.4.1, alors que Xalan lui-mme est dj parvenu  la
   version 2.5.1.

   Pour savoir quelle est la version installe actuellement :

 # java org.apache.xalan.xslt.EnvironmentCheck

   Pour plus d'informations, visitez
   http://xml.apache.org/xalan-j/faq.html
   [http://xml.apache.org/xalan-j/faq.html].

  5.2. Installation du XSL de Norman Walsh

   Durant cette phase, nous installerons le XSL de Norman Walsh dans
   le dossier /usr/local/dbtools/.

   Positionnez-vous dans le dossier /tmp/downloads, puis dcompressez
   et dpaquetez le fichier docbook-xsl.

 # cd /tmp/downloads/
 # gzip -d docbook-xsl-1.53.0.tar.gz
 # tar -xvf docbook-xsl-1.53.0.tar

   Pour installer docbook-xsl, dplacez les fichiers dans
   /usr/local/dbtools.

 # mv docbook-xsl-1.53.0 /usr/local/dbtool/docbook-xsl

   Ensuite, installez le XSL du TLDP.

  5.3. Installation du XSL du TLDP

   Dcompressez et dpaquetez le fichier tldp-xsl-xxxxx.tar.gz, puis
   copiez tous les fichiers dans le dossier
   /usr/local/dbtools/docbook-xsl/html.

 # cd /tmp/downloads
 # gzip tldp-xsl-xxxxx.tar.gz
 # gzip tldp-xsl-xxxxx.tar
 # mv tldp-html*.xsl /usr/local/dbtools/docbook-xsl/html

  5.4. Configuration de sitemap.xmap

   $COCOON_HOME pointe vers le dossier d'applications Internet de
   Cocoon. Ce dossier s'appelle typiquement
   /usr/local/jakarta-tomcat-4.1.9/webapps/cocoon/

   Crez un dossier nomm docbook dans $COCOON_HOME/mount. c'est l
   que nous mettrons tous nos contenus DocBook XML 4.1.2.

 # mkdir $COCOON_HOME/mount/docbook

   Crez un fichier nomm sitemap.xmap dans
   $COCOON_HOME/mount/docbook avec le contenu suivant :

 # cd $COCOON_HOME/mount/docbook
 # vi sitemap.xmap

 <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

     <!-- use the standard components -->
     <map:components>
         <map:generators default="file"/>
         <map:transformers default="xslt"/>
         <map:readers default="resource"/>
         <map:serializers default="html"/>
         <map:selectors default="browser"/>
         <map:matchers default="wildcard"/>
         <map:transformers default="xslt"/>
     </map:components>
      
     <map:pipelines>
         <map:pipeline>

    <map:match pattern="">
     <map:generate src="samples.xml"/>
     <map:transform
 src="/usr/local/jakarta-tomcat-4.1.9/webapps/cocoon/mount/editor/stylesheets/simple-page2html.xsl"/>
     <map:serialize/>
    </map:match>

             <!-- rpond aux requtes *.html avec
                  nos documents traits par .xsl -->
             <map:match pattern="*.html">
                 <map:generate src="{1}.xml"/>
                 <map:transform
                   src="/usr/local/dbtools/docbook-xsl/html/tldp-html.xsl"/>
                 <map:serialize type="html"/>
             </map:match>
            
             <!-- ensuite, rpond aux requtes *.pdf avec
                  nos documents traits par doc2pdf.xsl -->
             <map:match pattern="*.pdf">
                 <map:generate src="{1}.xml"/>
                 <map:transform
                   src="/usr/local/dbtools/docbook-xsl/fo/docbook.xsl"/>
                 <map:serialize type="fo2pdf"/>
             </map:match>

             <map:match pattern="*.xml">
                 <map:generate src="{1}.xml"/>
                 <map:serialize type="xml"/>
             </map:match>


         </map:pipeline>
     </map:pipelines>
 </map:sitemap>

  5.5. Accs  un contenu DocBook 4.1.2 XML dans un navigateur Internet

   Placez un fichier DocBook 4.1.2 XML dans le dossier
   $COCOON_HOME/mount/docbook/.

   Un fichier d'exemple est disponible 
   http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml
   [http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.xml].

   Maintenant, vous pouvez accder au document  l'aide d'un
   navigateur   http://localhost:8080/cocoon/mount/sample.html 
   (HTML) ou  http://localhost:8080/cocoon/mount/sample.pdf  (PDF).

6. Informations supplmentaires

   Cette section vous oriente vers des liens utiles sur l'Internet.

   Pour suggrer d'ajouter ici des ressources supplmentaires,
   crivez-moi  <saqib CHEZ seagate POINT com>. Merci.

  6.1. Groupes de nouvelles

   Voici quelques groupes de nouvelles dignes d'intrt :

    1. comp.text.sgml (facilement accessible par Google! Groups
       [http://groups.google.com/groups?group=comp.text.sgml])

    2. comp.text.xml (facilement accessible par Google! Groups
       [http://groups.google.com/groups?group=comp.text.xml])

    3. htmldoc.general (serveur -- news.easysw.com
       [http://news.easysw.com])

  6.2. Listes de diffusion

   On trouve ici quelques listes de diffusion pertinentes.

    1. Liste de diffusion DocBook d'OASIS. Visitez
       http://www.oasis-open.org/committees/docbook/mailinglist/index.shtml
       [http://www.oasis-open.org/committees/docbook/mailinglist/index.shtml]
       pour plus d'informations.

    2. Liste de diffusion DocBook du TLDP. Visitez
       http://www.tldp.org/mailinfo.html
       [http://www.tldp.org/mailinfo.html] pour plus d'informations.

    3. xml-doc de Yahoo Groups. Visitez
       http://groups.yahoo.com/group/xml-doc/
       [http://groups.yahoo.com/group/xml-doc/] pour plus
       d'informations.

  6.3. IRC

    1. Canal IRC DocBook en franais : #docbook-fr sur
       [8]irc://irc.freenode.net

    2. Canal IRC DocBook en anglais : #docbook sur
       [9]irc://irc.freenode.net

  6.4. Sites Internet

    1. http://www.oasis-open.org/ [http://www.oasis-open.org/], OASIS
       maintient un ventail de DTD DocBook

    2. http://www.xml-dev.com/blog/ [http://www.xml-dev.com/blog/],
       XML / XHTML WebLog

    3. http://docbook.org/wiki/moin.cgi/
       [http://docbook.org/wiki/moin.cgi/], le Wiki DocBook

    4. http://www.docbook.org/tdg/en/
       [http://www.docbook.org/tdg/en/], version en ligne (et en
       v.o.) du livre  DocBook : La rfrence 

    5. http://www.bureau-cornavin.com/opensource/crash-course/index.html
       [http://www.bureau-cornavin.com/opensource/crash-course/index.html],
       document sur la rdaction utilisant DocBook : A Crash Course

    6. http://www-106.ibm.com/developerworks/library/l-docbk.html
       [http://www-106.ibm.com/developerworks/library/l-docbk.html],
       un guide lger sur DocBook (excellente introduction)

    7. http://www.tldp.org/LDP/LDP-Author-Guide/index.html
       [http://www.tldp.org/LDP/LDP-Author-Guide/index.html], guide
       d'auteur issu du projet de documentation Linux (TLDP)

    8. http://www.tldp.org/authors/index.html#resources
       [http://www.tldp.org/authors/index.html#resources], ressources
       DocBook fournies par le TLDP

    9. http://www.traduc.org/docs/howto/lecture/DocBook-Demystification-HOWTO.html
       [http://www.traduc.org/docs/howto/lecture/DocBook-Demystification-HOWTO.html],
       Guide pratique (HOWTO) : Dmystification de DocBook de Eric
       Raymond

   10. http://www.xml-dev.com:8080/cocoon/mount/docbook/
       [http://www.xml-dev.com:8080/cocoon/mount/docbook/], site
       d'exemples de configuration de Tomcat + Cocoon + DocBook

  6.5. Applications de rdaction et de modelage du XML

   [10][Note] Note                               
              Une liste complte d'diteurs XML se trouve 
              http://www.xml-dev.com/blog/#19    
              [http://www.xml-dev.com/blog/#19]  

    1. eXchaNGeR -- Navigateur XML (et diteur XML) :
       http://xngr.org/ [http://xngr.org/]

    2. XERLIN -- Application de modelage du XML :
       http://www.xerlin.org/ [http://www.xerlin.org/]

    3. DocPro par Command Prompt, INC : http://www.commandprompt.com/
       [http://www.commandprompt.com/]

    4. YAWC Pro par XML Workshop LTD : http://www.yawcpro.com/
       [http://www.yawcpro.com/]. Peut tre utilis pour convertir
       des documents MS Word en simple DocBook XML.

    5. Logictran -- Convertisseur RTF : http://www.logictran.com/
       [http://www.logictran.com/]. Word/RTF vers HTML/XML.

    6. MajiX -- Convertisseur Word vers XML :
       http://www.tetrasix.com/ [http://www.tetrasix.com/]

    7. XMETAL par SoftQuad : http://www.softquad.com/
       [http://www.softquad.com/]

    8. diteur non-balis par i4i (DTD DocBook non-maintenues) :
       http://www.i4i.com/ [http://www.i4i.com/]

    9. diteur XML par XMLmind : http://www.xmlmind.com/xmleditor/
       [http://www.xmlmind.com/xmleditor/]

   10. upCast et downCast par Inifinity Loop :
       http://www.infinity-loop.de/en/products.html
       [http://www.infinity-loop.de/en/products.html]

   11. W2XML par DocSoft : http://www.docsoft.com/w2xmlv2.htm
       [http://www.docsoft.com/w2xmlv2.htm]

   12. XMLWrite par Wattle Software : http://xmlwriter.net/
       [http://xmlwriter.net/]

   13. oXygen -- diteur XML bas sur Java :
       http://www.oxygenxml.com/ [http://www.oxygenxml.com/]

   14. Xeena par IBM : http://www.alphaworks.ibm.com/tech/xeena
       [http://www.alphaworks.ibm.com/tech/xeena]

   15. Excosoft XML Client :
       http://www.excosoft.se/eweb/site/exc_pd.html
       [http://www.excosoft.se/eweb/site/exc_pd.html]

   16. Timelux Xpress : http://www.timelux.lu/html/Xpress2001.html
       [http://www.timelux.lu/html/Xpress2001.html]

   17. Morphon : http://www.morphon.com/ [http://www.morphon.com/]

   18. Conglomerate : http://conglomerate.org/
       [http://conglomerate.org/]

