Conversion de documents DocBook XML/SGML avec OpenJade

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.

Copyright 2001, Saqib Ali.

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:

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.

Merci de t��l��charger DocBook SGML v4.1, DocBook SGML v3.1, et DocBook XML v4.1.2.

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 LDP 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 LDP 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 paquetage nomm�� docbook-xsl.

T��l��chargez ��galement le XSL personnalis�� du LDP �� 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 LDP.

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

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:/usr/local/dbtools/dtd4.1.2/docbook.cat:/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 servlettes 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://xml.apache.org/cocoon/installing/index.html/. 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 desservir des contenus DocBook 4.1.2 XML.

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

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.