Conversion de documents DocBook XML/SGML avec OpenJade
Version française de DocBook XML/SGML Processing Using OpenJade
Saqib Ali
<saqib CHEZ seagate POINT com>
Traduction française: Guillaume Audirac
<guillaume POINT audirac CHEZ netpratique POINT fr>
Relecture de la version française: Encolpe Degoute
<encolpe CHEZ colpi POINT info>
Préparation de la publication de la v.f.: Jean-Philippe Guérard
<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 spécifiques 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 |
|----------------------------------------------------------------|
| Vérification 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 |
| supplémentaires. (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 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.3 | 2002-11-22 | SA |
|----------------------------------------------------------------|
| 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.2 | 2002-10-09 | AS |
|----------------------------------------------------------------|
| 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.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 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.3 | 2002-08-02 | SA |
|----------------------------------------------------------------|
| Ajout de la partie Informations supplémentaires. (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'énumérations. (Fixed |
| grammatical errors, numbered processes.) |
|----------------------------------------------------------------|
| Version 1.0 | 2002-06-29 | SA |
|----------------------------------------------------------------|
| 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
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. Préalable
2.2. OpenJade
2.3. Les DTD DocBook
2.4. Les entités ISO
2.5. Le DSSSL de Norman Walsh
2.6. Feuilles de style DSL personnalisées 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 entités 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. Accès à un contenu DocBook 4.1.2 XML dans un
navigateur Internet
6. Informations supplémentaires
6.1. Groupes de nouvelles
6.2. Listes de diffusion
6.3. IRC
6.4. Sites Internet
6.5. Applications de rédaction et de modelage du XML
1. Introduction
Quelques acronymes :
1. SGML -- Langage normalisé de balisage généralisé (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 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)
[http://www.gnu.org/copyleft/fdl.html] 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
[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)
[http://www.gnu.org/copyleft/fdl.html]; 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
[http://www.gnu.org/copyleft/fdl.html].
Une version française 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 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
[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 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)
[http://www.gnu.org/copyleft/fdl.html]; 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
[http://www.gnu.org/copyleft/fdl.html].
1.3. Remerciements
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 <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 suggérer la
partie sur HTMLDOC (PDF -> HTML).
5. Lloyd D. Budd <ldp CHEZ foolswisdom POINT org> pour ses
propositions d'amélioration 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 définition de type de document (Document Type
Definition ou DTD). DocBook décrit 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 définit la syntaxe d'un document -- c'est principalement
un livre de règles qui décrit un ensemble de balises et
d'attributs, qui seront utilisés pour décrire des types
spécifiques de contenus. Ainsi, DocBook est un livre de règles
utilisé pour écrire des documents. Chaque balise utilisée dans la
rédaction du document, doit être définie spécifiquement et
formellement dans la DTD.
1.5. Qu'est ce qu'un DSSSL ?
C'est un langage de symboles et de spécifications de style de
document (Document Style Semantics and Specification Language ou
DSSSL). Il définit 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 nécessaires à la configuration d'OpenJade pour
convertir le SGML et le XML :
o OpenJade
o Les DTD DocBook
o Les entités 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
téléchargement sur Internet. Le chapitre suivant
explique comment les télécharger.
1.7. Conditions
Ce document considère que ce qui suit est déjà installé sur votre
système :
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 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)
[http://www.tldp.org/authors/index.html#resources].
2.1. Préalable
Créez un dossier /tmp/downloads. Nous l'utiliserons pour stocker
les codes sources téléchargés.
2.2. OpenJade
OpenJade sera utilisé pour traiter les documents DocBook. OpenJade
peut être téléchargé à http://openjade.sourceforge.net/
[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.
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 télécharger 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 télécharger toutes les archives au format
compressé zip.
2.4. Les entités ISO
Le projet de documentation Linux (The Linux Documentation Project
[http://www.tldp.org]) 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
[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 téléchargé 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 rédaction de ce document, docbook-dsssl-1.76 était
disponible.
2.6. Feuilles de style DSL personnalisées par le TLDP
Le DSL du TLDP est une feuille de style personnalisée et utilisée
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 arrière-plan ou une table des matières.
Il peut être téléchargé à
http://www.tldp.org/authors/tools/ldp.dsl
[http://www.tldp.org/authors/tools/ldp.dsl].
Le fichier ldp.dsl nécessite le DSSSL de Norman Walsh.
2.7. HTMLDOC (optionnel)
HTMLDOC peut être utilisé pour convertir le HTML en PDF. Si vous
souhaitez créer des documents PDF, téléchargez 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 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/
[http://sourceforge.net/projects/docbook/].
Téléchargez le paquet nommé docbook-xsl.
[5][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 <saqib CHEZ seagate POINT com>
2.9. Le XSL personnalisé du TLDP (optionnel)
Téléchargez é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 appropriés. Tous vont dans /usr/local/dbtools/. Créez ce
dossier à l'aide de la commande suivante :
# mkdir /usr/local/dbtools
3.1. Installation d'OpenJade
Cette procédure 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, réalisez les opérations suivantes
:
1. Positionnez-vous dans le dossier /tmp/downloads.
# cd /tmp/downloads
2. Décompressez le fichier.
# gzip -d openjade-1.3.x.tar.gz
3. Dépaquetez le fichier.
# tar -xvf openjade-1.3.x.tar
4. Déplacez-vous dans le dossier openjade-1.3
# cd openjade-1.3.x
5. Exécutez la commande ./configure.
# ./configure --prefix=/usr/local/dbtools/openjade
6. Exécutez la commande make.
# make
7. Exécutez la commande make install. Dès maintenant, les
fichiers binaires d'OpenJade seront installés 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. Décompressez le fichier.
# gzip -d docbook-dsssl-1.76.tar.gz
3. Dépaquetez le fichier.
# tar -xvf docbook-dsssl-1.76.tar
4. Déplacez-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. Créez trois nouveaux dossiers, nommés dtd3.1, dtd4.1, et
dtd4.1.2.
# mkdir dtd3.1
# mkdir dtd4.1
# mkdir dtd4.1.2
3. Déplacez-vous dans le dossier dtd3.1.
# cd dtd3.1
4. Décompressez le fichier DocBook SGML v3.1 dans ce dossier.
# unzip /tmp/downloads/docbk31.zip
5. Déplacez-vous dans le dossier dtd4.1.
# cd ../dtd4.1
6. Décompressez le fichier DocBook SGML v4.1 dans ce dossier.
# unzip /tmp/downloads/docbk41.zip
7. Déplacez-vous dans le dossier dtd4.1.2.
# cd ../dtd4.1.2
8. Décompressez le fichier DocBook XML v4.1.2 dans ce dossier.
# unzip /tmp/downloads/docbk412.zip
3.4. Installation des entités ISO
Dans cette section, nous installerons les entités ISO que nous
avons téléchargées sur le site Internet du TLDP.
Tout d'abord, nous installons les entités 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. Décompressez le fichier.
# gzip -d entities.tar.gz
4. Dépaquetez le fichier.
# tar -xvf entities.tar
Ensuite, nous installons les entités 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. Décompressez le fichier.
# gzip -d entities.tar.gz
4. Dépaquetez le fichier.
# tar -xvf entities.tar
3.5. Installation du DSL du TLDP
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>
]]>
3.6. Installation de HTMLDOC
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...
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. Définition de la variable environnementale SGML_CATALOG_FILES
pour le SGML
La variable SGML_CATALOG_FILES doit être définie pour pointer sur
les fichiers catalog appropriés. Pour définir 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 créer un document d'une pièce (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 télécharger 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. Définition de la variable environnementale SGML_CATALOG_FILES
pour le XML
La variable SGML_CATALOG_FILES doit être définie pour pointer sur
les fichiers catalog appropriés. Pour définir 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, créez un fichier HTML d'une pièce à 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, exécutez HTMLDOC pour générer 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é-interprétée (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 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
[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.
[7][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
[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 décompressez
et dépaquetez 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, déplacez 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
Décompressez et dépaquetez 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/
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>
5.5. Accès à 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 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).
6. Informations supplémentaires
Cette section vous oriente vers des liens utiles sur l'Internet.
Pour suggérer d'ajouter ici des ressources supplémentaires,
écrivez-moi à <saqib CHEZ seagate POINT com>. Merci.
6.1. Groupes de nouvelles
Voici quelques groupes de nouvelles dignes d'intérêt :
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 français : #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 référence »
5. http://www.bureau-cornavin.com/opensource/crash-course/index.html
[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
[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
[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) : Démystification 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 rédaction et de modelage du XML
[10][Note] Note
Une liste complète 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/]
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
ebac5394abc62d2e0b61505bfba9712a
>
files
>
62
