             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 gmail 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.1

   2006-05-10

   +------------------------------------------------------------------------+
   | Historique des versions                                                |
   |------------------------------------------------------------------------|
   | Version 2.2.8.fr.1.1          | 2006-05-10         | JPG               |
   |------------------------------------------------------------------------|
   | Mise  jour de l'adresse lectronique de Guillaume Audirac.            |
   |------------------------------------------------------------------------|
   | 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/]

