Sommaire

Installation des modules manquants
Import des modèles docbook

Docbook

Docbook est une technologie XML mise au point pour réaliser des documentations. Docbook centre son intérêt, non pas sur la mise en page, mais sur les données de façon à avoir un document léger, facile à comprendre et aisé à traiter.

Docbook est le point de départ d'un certain nombre de publications. En effet, à partir d'un document docbook, il est possible de générer :

du contenu web : XML, XHTML, HTML, ...
du contenu interchangeable : RTF, ...
du contenu portable : PDF, ...
du contenu imprimable : PS, ...
et encore un grand nombre de format.

ces publications pouvant être automatisées, il devient donc aisé de ne se concenter que sur les informations plutôt que la mise en page.

d'autre part, docbook étant écrit en XML, il est aisé de travailler sur un même document à plusieurs (--> gestion de versions).

Choix d'un éditeur pour docbook

Docbook étant du XML pur, n'importe quel éditeur de texte suffit. Cependant :

il existe pas moins de 400 balises utilisables pour un document et il devient très vient impossible de se souvenir de tout. Le plus simple est d'utiliser un éditeur capable de vérifier dynamiquement la validité du document en cours de rédaction, de proposer les différentes balises, etc.
Si l'on veut travailler à plusieurs sur un document, mieux vaut utiliser un éditeur capable de gérer les versions (CVS, SVN, etc.)
Un éditeur WYSIWYG n'est pas forcément utile car l'expérience montre qu'un utilisateur est finalement plus à l'aise avec un éditeur textuel, pour peu qu'il se donne la peine de pratiquer un peu.

Pour toutes ces raisons, il faut rechercher un éditeur plus élaboré. sur le site docbook, on peut télécharger le menu docbook pour emacs. Celui-ci gérant aussi CVS, il semble être un outil de choix. mais la difficulté d'obtenir des informations sur sa configuration m'a fait pencher vers Eclipse.

Eclipse possède un environnement capable à la fois de composer des documents XML conformes à une DTD dynamiquement et de gérer les accès concurrents.

Ce document présente donc la mise en place et l'utilisation de docbook avec Eclipse.

Pré-requis

Eclipse Europa (v3.3) en anglais car la traduction française n'est pas encore disponible
la dernière DTD docbook disponible en téléchargement (v1.74).

Mise en place

Avant toute chose, un rapide tour sur la toile à la recherche d'informations nous font tomber sur un documents IBM expliquant l'installation de docbook sous eclipse. mais, en suivant les instructions, on se rend compte que cela ne fonctionne pas. La version d'eclipse utilisée n'est pas la même, les options présentées sont indisponibles sur la version de base Europa. il faut donc les installer.

Installation des modules manquants

Pour cela, il faut aller dans Help > Software Updates > Find and install et sélectionner Search for new features to install. Sélectionnez ensuite Europa Discovery Site et répondez aux questions de configuration. Après chargement, vous devriez obtenir :

Recherchez ensuite tout ce qui concerne l'édition ou la modélisation XML/XSL ou XSD :

Eclipse XML Ediors
XML Schema Infoset Model
Eclipse Modeling Framework (EMF)
WST Common UI

Cliquez aussi sur le bouton Select Required qui permettra de sélectionner aussi toutes les dépendances.

Validez. Les modules s'installent. Eclipse vous demandera de redémarrer. La gestion du XML est en place. Un onglet XML est présent.

Création d'un projet Eclipse

créez un nouveau projet File > New > Project, par exemple DocBook, puis créez un répertoire afin d'y placer les modèles. Pour cela, dans la Navigator, cliquez sur votre porjet, un clic sur le bouton droit, New > Folder. Appelez-le Modèles, par exemple. Il contiendra les modèles, schémas, DTD et XSL.

Créez aussi un autres répertoire qui contiendra votre travail. un répertoire doc, par exemple.

Import des modèles docbook

Il faut maintenant importer les modèles (DTD, XSL, etc) docbook afin de pouvoir générer des documents. Pour cela, après avoir téléchargé les fichiers sur le site officiel sans les décompresser, ouvrez File > Import :

et sélectionnez Archive File et cliquez sur Next :

Sélectionnez votre fichier (Browse). Commençons par docbook-xml-4.5.zip, qui contient la DTD docbook v4.5 :

Sélectionnez tout (select all) puis l'endroit où vous voulez l'importer (Browse) :

Choisissez votre répertoire (projet) - ici DocBook - et le sous répertoire modèles puis validez. Faites de même avec docbook-xsl-1.74.0.zip contenant les XSL nécessaires aux conversions :

Vous êtes prêt à travailler !

Création d'un document

Pour créer un nouveau document, sélectionnez File > New > Other :

Sélectionnez XML dans la section XML et validez (Next) :

Sélectionnez l'endroit où il faudra le créer (DocBook/doc) et le nom du fichier, par exemple Essai.xml, puis cliquez sur Next :

Reliez le fichier à la DTD docbook en cliquant sur Create XML file from a DTD file, puis Next :

Dans les modèles (DocBook/modèles), sélectionnez docbookx.dtd, puis Next :

Choisissez l'élément racine de votre document en fonction du document que vous voulez générer. Si vous ne savez pas, reportez vous à la documentation Docbook. Par exemple, pour un livre, choisissez book, puis Finish :

Le document est créé. Remarquez les deux onglets en bas, l'un indique la structure et l'autre, le code XML :

Il ne reste plus qu'à compléter le document. Pour chaque niveau, l'onglet design indique les balises créées, mais aussi les sous-éléments disponibles. Par exemple, comme on peut le voir, l'élément book admet pour sous-élément title, subtitle, etc.

Mais ce n'est pas tout, si vous modifiez le document côté source, une aide contextuelle s'affiche automatiquement :

Il ne vous reste plus qu'à choisir la balise qui vous convient...

Installation Docbook