Sommaire

Installation et configuration du processeur XSL

Conversion ou génération aisée d'un document au format DocBook

Nous avons vu comment installer et utiliser DocBook sous Eclipse. Nous allons voir maintenant comment, une fois que nous avons rédigé un document, comment le transformer.

Un exemple de document

Prenons comme exemple le document suivant :

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
<title>Un exemple de livre DocBook</title>
<titleabbrev>Exemple</titleabbrev>
<bookinfo>
<author>
<personname>
<firstname>Christopher</firstname>
<surname>COMPAGNON</surname>
</personname>
</author>
</bookinfo>
<preface id="preface1">
<title>Une préface simple</title>
<para>Rien de plus simple pour créer un paragraphe</para>
</preface>
<chapter id="chapter1">
<title>Chapitre premier</title>
<para>Un livre doit contenir au minimum un chapitre</para>
<para>Et hop, un autre paragraphe!!!</para>
<important>
<para>Et ici, quelque chose de très important</para>
</important>
<tip>
<para>Une astuce !</para>
</tip>
<caution>
<para>
Encore une chose <code>importante</code>, sinon cela passera inaperçu !
</para>
</caution>
<example>
<title>Exemple numéro 1</title>
<programlisting>Le code d'un programme ici</programlisting>
</example>
</chapter>
</book>

Cet exemple est créé dans le projet DocBook, dans le répertoire doc. ce répertoire a été choisi pour l'exemple, n'importe quel autre répertoire du projet aurait bien fait l'affaire.

Remarque

Nous avons choisi ici de créer un document à partir du modèle DocBook 4.5, validé par OASIS. Nous eussions pu utiliser la DTD locale.

Installation et configuration du processeur XSL

Nous allons utiliser le processeur fourni par Apache et qui s'intègrera parfaitement dans Eclispe : Xalan.

Pour cela, téléchargeons-le depuis le site officiel. Dans notre exemple, il s'agit de xalan-j_2_7_1-bin.zip. Ne le décompressez pas !

Par défaut, Eclipse ne connaît pas de processeur XSL, sauf si l'on en déjà installé un. Pour indiquer à Eclipse d'utiliser votre processeur XSL fraîchement téléchargé, allez dans Window > Preference, puis dans les propriétés Ant > runtime :

Sélectionnez Ant Home Entries puis cliquer sur le bouton Add External JARs dans le panneau de droite et sélectionnez votre processeur XSL (xalan-j_2_7_1-bin.zip). Installer tout. Eclipse va vous demander dans quel répertoire. Choisissons par exemple lib. Un nouveau répertoire apparaît avec tout son contenu (Xalan).

Dans b>Ant Home Entries apparaissent des lignes correspondant à votre processeur XSL et pointant sur votre projet local.

Nous sommes prêts à compiler nos documents et générer d'autres formats.

build.xml

Pour compiler de façon puis aisée, surtout si vous travaillez à plusieurs, rien ne vaut un fichier de directive de compilation.

Sous Eclipse, il s'agit par défaut de build.xml. Pour en créer un nouveau pour le projet, allez dans File > New > File et créez un fichier build.xml sous votre projet DocBook.

Ouvrez ce fichier (vide par défaut) et insérez, par exemple, le contenu suivant pour générer du xhtml:

<?xml version="1.0"?>

<project name="doc" default="usage">
<description>
Test pour une compilation DocBook automatisée avec Ant
</description>


<property name="docbook.xsl.dir" value="modeles/docbook-xsl-1.74.0" />
<property name="doc.dir" value="doc" />
<property name="html.dir" value="generation/html" />
<property name="html.stylesheet" value="${docbook.xsl.dir}/xhtml/docbook.xsl" />
<property name="xalan.lib.dir" value="lib/xalan-j_2_7_1" />


<path id="xalan.classpath">
<fileset dir="${xalan.lib.dir}" id="xalan.fileset">
<include name="xalan.jar" />
<include name="xercesImpl.jar" />
</fileset>
</path>


<target name="usage" description="Prints the Ant build.xml usage">
<echo message="Use -projecthelp to get a list of the available targets." />
</target>


<target name="clean" description="Cleans up generated files.">
<delete dir="${doc.dir}" />
</target>


<target name="depends">
<mkdir dir="${doc.dir}" />
</target>


<target name="build-html" depends="depends"
description="Generates HTML files from DocBook XML">
<xslt style="${html.stylesheet}" extension=".html"
basedir="doc" destdir="${doc.dir}">
<classpath refid="xalan.classpath" />
</xslt>
</target>

</project>

Reamarque

Notez particulièrement que l'on choisit la feuilel de style pour la génération du document :

<property name="html.stylesheet" value="${docbook.xsl.dir}/xhtml/docbook.xsl" />

Ici, l'on voit que c'est la génération de xhtml qui a été choisie. Mais l'on pourrait en prendre d'autres, en fonction du document désiré. Il suffit de chercher la bonne DTD dans les modèles téléchargés.

Modifiez-le si nécessaire.

Compiler

Maintenant que buil.xml est réalisé, il ne reste qu'à compiler. Compilez :Run > External Tools > DocBook build.xml ou encore en cliquant sur le fichier build.xml avec le bouton droit et en sélectionnant Run as dans le menu contextuel. Une fenêtre doit s'ouvrir.

Vous reconnaissez les différentes sections définies dans build.xml. Veillez à sélectionner buil-html puis cliquez sur Run.

Si tout est bien configuré, la compilation commence et s'achève sans erreur quelques secondes plus tard.

Allez dans votre répertoire de travail, rafraîchissez (clic-droit: refresh) et vous devriez voir votre fichier html généré.

Vous pouvez le visualiser (clic-droit : Open).

Et voilà !

Il ne reste plus qu'à réaliser ajouter d'autres compilations, de créer ses porpores feuilles de style afin de personnaliser la chaîne de prodution et d'obtenir ce qui est nécessaire.

Conversion ou génération aisée d'un document au format DocBook

Nous venons de le voir, l'interface proposée par Eclipse, bien que simple à utiliser, n'est pas forcément aussi conviviale que les applications que nous avons l'habitude d'utiliser. Sans compter que souventes fois l'on dispose comme source que d'un document réalisé sous un traitement de texte ( micorosoft Word, OpenOfficeWriter, etc.) et qu'on se voit mal tout réécrire pour adapter le document à une chaîne de production automatique. Pour convertir un document existant ou en créer un nouveau de façon plus aisée et conviviale, rien de plus simple. Pour celà, utilisez OpenOfficeWriter lequel devrait lire le docuement d'origine sans aucun souci particulier tellement il sait lire de formats différents puis, prenez soin d'enregistrer une copie de ce document au format DocBook (.xml). Il ne vous reste plus alors qu'à importer ce document dans Eclipse et de l'ajuster à votre chaîne de production.

Compilation de documents Docbook