Conversion de documents DocBook XML/SGML avec OpenJade

	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
	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 :

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.

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.

Voici les outils nécessaires à la configuration d'OpenJade pour convertir le SGML et le XML :

	Note
	Tous ces paquets sont libres et disponibles en téléchargement sur Internet. Le chapitre suivant explique comment les télécharger.

Ce document considère que ce qui suit est déjà installé sur votre système :

Créez un dossier /tmp/downloads. Nous l'utiliserons pour stocker les codes sources téléchargés.

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.

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

Veuillez télécharger DocBook SGML v4.1, DocBook SGML v3.1, et DocBook XML v4.1.2.

	Note
	Veuillez télécharger toutes les archives au format compressé zip.

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

Lors de la rédaction de ce document, docbook-dsssl-1.76 était disponible.

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.

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.

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

Téléchargez également le XSL personnalisé du TLDP à http://my.core.com/~dhorton/docbook/tldp-xsl/.

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 :

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

Dans cette section, nous installerons les DTD DocBook.

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.

Ensuite, nous installons les entités ISO pour la DTD 4.1 SGML.

Enfin, nous installons la feuille de style personnalisée du TLDP.

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

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

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

# 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

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

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

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

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.

	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.

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.

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

$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).

Voici quelques groupes de nouvelles dignes d'intérêt :

On trouve ici quelques listes de diffusion pertinentes.