Conversion de documents DocBook XML/SGML avec OpenJade

Version française de DocBook XML/SGML Processing Using OpenJade

Encolpe Degoute

Relecture de la version française

Version : 2.2.8.fr.1.1

2006-05-10

Historique des versions
Version 2.2.8.fr.1.12006-05-10JPG
Mise à jour de l'adresse électronique de Guillaume Audirac.
Version 2.2.8.fr.1.02003-08-29GA, 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.82003-07-16ES
Ajout d'information sur la mise à jour des JRE pour Cocoon. (Added info about keeping JREs up-to-date for Cocoon)
Version 2.2.72003-07-09ES
Restitution du lien rompu et d'autres fichiers spécifiques sur le XSL du TLDP. (Fixed broken links to LDP XSL and other LDP XSL specific filenames.)
Version 2.2.62003-06-16SA
Vérification de l'instruction sur DocBook XSL 1.57. (Verified the instruction against docbook XSL 1.57.)
Version 2.2.52003-05-16SA
Restitution des liens rompus dans la partie Informations supplémentaires. (Fixed the broken links in the external resources section.)
Version 2.2.42003-04-20SA
Mise à jour des liens vers le nouveau site de démonstration. Ajout de nouveaux liens dans la partie Informations supplémentaires. (Updated links to the new Demo Site. Added new links to the resources section.)
Version 2.2.32002-11-22SA
Ajout de suggestions d'utilisateurs. Ajout de nouveaux liens dans la partie Informations supplémentaires. (Added the suggestion made by users. Added new links to the resources section.)
Version 2.2.22002-10-09AS
Cette mise à jour corrige quelques autres erreurs typographiques, supprime quelques espaces qui défiguraient 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.12002-10-09SA
Correction de l'adresse URL vers le fichier d'exemples. (Fixed the URL to the Sample Files.)
Version 2.22002-09-29AS
Corrections mineures dans la partie sur Cocoon. (Minor corrections to the Cocoon section.)
Version 2.12002-09-15SA
Corrections mineures dans la partie sur Cocoon. (Minor corrections to the Cocoon section.)
Version 2.02002-09-10SA
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.52002-08-11SA
Ajout de la partie sur XML et du fichier d'exemples XML. (Added the XML section and the sample XML file.)
Version 1.42002-08-08SA
Nombreuses et précieuses modifications et corrections suggérées par Lloyd D. Budd. Merci Lloyd :) (Many valuable modifications/corrections suggested by Lloyd D. Budd. Thanks Lloyd. :))
Version 1.32002-08-02SA
Ajout de la partie Informations supplémentaires. (Added the "Additional Resources" section.)
Version 1.22002-07-23SA
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.12002-07-19KET
Correction de fautes grammaticales et d'énumérations. (Fixed grammatical errors, numbered processes.)
Version 1.02002-06-29SA
Version publique initiale. (Initial public release.)

Résumé

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


Table des matières

Introduction
Droits d'utilisation
Copyright et licence
Remerciements
Qu'est-ce que DocBook ?
Qu'est ce qu'un DSSSL ?
De quoi avons-nous besoin ?
Conditions
Les indispensables
Préalable
OpenJade
Les DTD DocBook
Les entités ISO
Le DSSSL de Norman Walsh
Feuilles de style DSL personnalisées par le TLDP
HTMLDOC (optionnel)
Le XSL de Norman Walsh (optionnel)
Le XSL personnalisé du TLDP (optionnel)
Installation des outils de conversion — OpenJade
Installation d'OpenJade
Installation du DSSSL de Norman Walsh
Installation des DTD DocBook
Installation des entités ISO
Installation du DSL du TLDP
Installation de HTMLDOC
Utilisation d'OpenJade
Traitement du SGML
Traitement du XML
HTML vers PDF (optionnel)
Publier DocBook 4.1.2 XML
Tomcat + Cocoon
Installation du XSL de Norman Walsh
Installation du XSL du TLDP
Configuration de sitemap.xmap
Accès à un contenu DocBook 4.1.2 XML dans un navigateur Internet
Informations supplémentaires
Groupes de nouvelles
Listes de diffusion
IRC
Sites Internet
Applications de rédaction et de modelage du XML

Quelques acronymes :

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.

[Note]Note

Le texte ci-dessous est la version française de la licence de ce document. Seule la version originale de cette licence, présentée dans la section suivante, fait foi.

Copyright © 2001, Saqib Ali.

Copyright © 2003, Guillaume Audirac, Encolpe Degoute et Jean-Philippe Guérard pour la version française.

La version originale de ce document a été réalisée 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) version 1.1 ou ultérieures, telle que publiée par la Free Software Fondation (FSF); sans section invariante, sans texte de première de couverture ni texte de quatrième de couverture. Une copie de la licence est disponible à http://www.gnu.org/copyleft/fdl.html.

La version française de ce document a été réalisée par Guillaume Audirac et Encolpe Degoute. La version française de ce guide pratique est publiée en accord avec les termes de la licence de documentation libre GNU (GFDL); sans section invariante, sans texte de première de couverture ni texte de quatrième de couverture. Une copie de la licence est disponible à http://www.gnu.org/copyleft/fdl.html.

Une version française non-officielle de cette licence est disponible à http://cesarx.free.fr/gfdlf.html.

[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 français de sa traduction.

Copyright © 2001, Saqib Ali.

Copyright © 2003, Guillaume Audirac, Encolpe Degoute et Jean-Philippe Guérard pour la version française.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, 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.

La version française de ce document a été réalisée par Guillaume Audirac et Encolpe Degoute. La version française de ce guide pratique est publiée en accord avec les termes de la licence de documentation libre GNU (GFDL); sans section invariante, sans texte de première de couverture ni texte de quatrième de couverture. Une copie de la licence est disponible à http://www.gnu.org/copyleft/fdl.html.

Toute la gloire revient à Allah, le Maître des Mondes. Tout le mérite revient à Allah. La moindre erreur dans ce document est de ma propre faute.

De plus, j'aimerais remercier les personnes suivantes pour leurs précieuses contributions à ce document :

  1. Eric Safern pour les mises à jour concernant Cocoon et le JRE. http://www.timebytes.com/.

  2. Greg Ferguson pour ses judicieuses suggestions et astuces sur la liste de diffusion de DocBook.

  3. Kristin Thomas pour la relecture initiale de la version originale de ce document.

  4. Luc de Louw pour avoir suggérer la partie sur HTMLDOC (PDF → HTML).

  5. Lloyd D. Budd pour ses propositions d'amélioration de la plupart des parties de ce document.

  6. Andrew Shugg pour la correction des erreurs de la version 2.0 de ce document. Neep Consulting.

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

La plupart des paquets nécessaires sont situés sur le site Internet du projet de documentation Linux (The Linux Documentation Project ou TLDP).

OpenJade sera utilisé pour traiter les documents DocBook. OpenJade peut être téléchargé à http://openjade.sourceforge.net/.

Lors de la rédaction de ce document, OpenJade version 1.3.1 était disponible. Téléchargez le fichier openjade-1.3.x.tar.gz.

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

Le DSL du TLDP est une feuille de style personnalisée et utilisée par The Linux Documentation Project (TLDP). C'est une prolongation du DSSSL de Norman Walsh. Il y ajoute plusieurs choses comme un arrière-plan ou une table des matières. Il peut être téléchargé à http://www.tldp.org/authors/tools/ldp.dsl.

Le fichier ldp.dsl nécessite le DSSSL de Norman Walsh.

Ceci n'est pas indispensable. Mais si vous désirez reconnaître 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 téléchargeables à http://sourceforge.net/projects/docbook/.

Téléchargez le paquet nommé docbook-xsl.

[Note]Note

Récemment, docbook-xsl version 1.57.0 a été rendu publique. Ce document est valide avec la dernière version, et des changements adéquats ont été effectués. Si vous rencontrez encore des erreurs, merci de m'écrire à l'adresse

Dans cette section, nous installerons tous les outils dans les dossiers appropriés. Tous vont dans /usr/local/dbtools/. Créez ce dossier à l'aide de la commande suivante :

# mkdir /usr/local/dbtools

Enfin, nous installons la feuille de style personnalisée 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 refléter le chemin absolu du fichier docbook.dsl. Voici la zone originale du fichier qui doit être adaptée :

    <![%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>
    ]]>
    

Cette étape est facultative. Elle est utile seulement si vous désirez créer des documents PDF à partir de HTML.

Retournez dans le dossier des téléchargements.

# cd /tmp/download

Décompressez et dépaquetez 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

Exécutez configure pour définir le chemin d'installation.

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

Lors de la rédaction de ce document, HTMLDOC version 1.8.20-1 était disponible. Cette version connaît un problème de fontes dans le fichier Makefile. Il devrait se plaindre à l'installation des fontes, parce qu'elles ne sont pas disponibles sur le système.

Voici l'erreur obtenue lorsque vous exécuterez 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 problème d'installation, éditez le fichier fonts/Makefile et mettez en commentaires les lignes référencées aux fontes ZapfChancery et ZapfDingbats.

Ensuite, exécutez 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...

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

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

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

[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/.

Dans cette section, nous verrons comment publier un contenu DocBook 4.1.2 XML avec 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.

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

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

Une fois Cocoon + Tomcat configurés et opérationnels, poursuivez aux sections suivantes pour publier des contenus DocBook 4.1.2 XML.

[Note]Avertissement important :

les spécialistes ont rencontré des problèmes 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 défaut.

En dernier lieu, assurez-vous d'utiliser la toute dernière version du JRE de Sun (1.4.2 à la rédaction de ce document).

De même, mettez à jour l'analyseur Xalan avec sa dernière version. Pour ma part, la dernière version 1.4.2 du JRE de Sun est fournie avec Xalan 2.4.1, alors que Xalan lui-même est déjà parvenu à la version 2.5.1.

Pour savoir quelle est la version installée actuellement :

# java org.apache.xalan.xslt.EnvironmentCheck

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

$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/

Créez 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

Créez 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>

            <!-- répond aux requêtes *.html avec 
                 nos documents traités 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, répond aux requêtes *.pdf avec 
                 nos documents traités 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>

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.

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

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

Pour suggérer d'ajouter ici des ressources supplémentaires, écrivez-moi à . Merci.

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

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

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

  4. http://www.docbook.org/tdg/en/, version en ligne (et en v.o.) du livre « DocBook : La référence »

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

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

  7. 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, ressources DocBook fournies par le TLDP

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

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

[Note]Note

Une liste complète d'éditeurs XML se trouve à http://www.xml-dev.com/blog/#19

  1. eXchaNGeR — Navigateur XML (et éditeur XML) : http://xngr.org/

  2. XERLIN — Application de modelage du XML : http://www.xerlin.org/

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

  4. YAWC Pro par XML Workshop LTD : 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/. Word/RTF vers HTML/XML.

  6. MajiX — Convertisseur Word vers XML : http://www.tetrasix.com/

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

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

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

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

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

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

  13. oXygen — Éditeur XML basé sur Java : http://www.oxygenxml.com/

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

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

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

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

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