TP d`initiation `a DocBook et `a CVS

TP d’initiation à DocBook et à CVS
avec l’IDE eclipse
Axe ISI - Philippe Beaune
Jeudi 30 septembre 2004 matin / 2h00
Résumé
Ce T.P. consiste en la découverte du format de données XML, DocBook. Il est proposé de manipuler ce format avec l’IDE eclipse. De plus,
l’objectif du cours étant de se familiariser avec le TCAO (Travail Collaboratif Assisté par Ordinateur), vous serez amené à réaliser collaborativement un document collectif, et pour cela vous utiliserez CVS (Concurrent
Versions System), toujours au sein de l’IDE eclipse.
1
Objectif et moyens
À l’issue de ce T.P., vous devrez savoir utiliser le format DocBook, les DTD,
les fichiers XSL, et générer aussi bien des fichiers HTML, que des fichiers PostScript ou PDF, à partir d’un (ou plusieurs) fichier(s) DocBook, dans l’environnement eclipse. À l’issue de ce T.P., vous aurez aussi quelques notions de
versioning, à travers l’utilisation de la fonctionnalité CVS d’eclipse
Le logiciel eclipse est déjà installé dans les salles de TP (aussi bien sous
Linux, que sous Windows). En revanche un certain nombre de plugins et de
fichiers DTD et XSL sont à ajouter dans votre espace de travail pour manipuler
tous ces concepts.
Tous ces fichiers se trouvent à l’url :
– http://www.emse.fr/~beaune/eclipse/
Avant de télécharger quoi que ce soit, créez-vous un nouveau répertoire dans
lequel vous allez placer tous ces éléments. Ils sont tous compressés au format
zip, et vous devez tous les décompresser dans ce répertoire nouvellement créé,
surtout sans en changer le contenu : les arborescenses décompressées doivent
rester telles qu’elles vous sont fournies.
– la DTD de DocBook : docbook-xml-4.2.zip qui vous permettra de valider syntaxiquement vos réalisations DocBook, et vous fournira aussi une
aide syntaxique dans l’éditeur d’eclipse ;
– les fichiers XSL de DocBook : docbook-xsl-1.66.1.zip qui permettront,
à partir de fichiers DocBook, de générer du HTML ou du XSL-FO (principalement) ;
– le plugin transclipse : transclipse-0.20.0.zip qui permet de transformer des fichiers XML (avec XSL) ;
1
– la bibliothèque FOP : fop-0.20.5.zip qui vous permettra de générer du
PDF ou du PostScript (principalement) à partir du format XSL-FO dans
transclipse ;
– le plugin XML-Buddy : xmlbuddy-2.0.9.zip qui offre une nouvelle perpective à eclipse (et des fonctionnalités associées !), pour manipuler des
fichiers XML ;
– et enfin la bibliothèque SAXON : saxon-6.5.3.zip qui contient les classes
Java nécessaires à transclipse pour manipuler les fichiers XSL.
Vous remarquerez qu’à cette url (http://www.emse.fr/~beaune/eclipse/),
se trouve une dernière archive (tdg-en-html-2.0.10.zip) : il s’agit d’une version HTML du célèbre livre :
– DocBook : The Definitive Guide
qui contient (à quelques erreurs près !) la définition de toutes les balises DocBook.
Pas besoin d’installer ce livre sur votre machine dans l’immédiat : vous pouvez
y accéder directement à l’url :
– http://www.docbook.org/tdg/en/html/docbook.html.
2
Configuration d’eclipse
Pré-requis :
– vous avez téléchargé les 6 archives .zip,
– vous les avez décompressées, et
– vous avez lancé eclipse.
Installation des plugins de base : cette installation peut se faire sans
toucher à l’installation d’eclipse. D’ailleurs, n’étant pas vous-mêmes Administrateur de la machine qui vous est confiée, vous ne pourriez pas le faire. On va donc
se contenter d’indiquer à eclipse où aller chercher des plugins supplémentaires
(et cela ne vaudra que pour vous, et ne modifiera pas le comportement d’eclipse
pour d’autres utilisateurs sur cette machine : génial ! Non ?).
– menu Help, sous-menu Software Updates, item Manage Configuration ... : choisissez Add an Extension Location ; allez retrouver
le plugin XML-buddy là où vous l’avez déposé (sélectionnez le répertoire
xmlbuddy) ; et acceptez le redémarage d’eclipse.
– menu Help, sous-menu Software Updates, item Manage Configuration ... : choisissez Add an Extension Location ; allez retrouver
le plugin transclipse là où vous l’avez déposé (sélectionnez le répertoire
transclipse) ; et acceptez à nouveau le redémarage d’eclipse (c’est un
peu long, mais il faut en passer par là. Patience ...).
Configuration de ces plugins :
– menu Window, item Preferences : XMLBuddy devrait être ok.
– choisissez donc l’autre : transclipse ; ajoutez une XSLT processor en allant chercher le fichier saxon.jar là où vous aviez déposé l’archive saxon ;
sélectionnez ce nouveau XSLT processor : SAXON 6.5.3 from ....
– toujours dans cette fenêtre de transclipse, pour la XSL Stylesheet
detection method, choisissez No detection ..., et sélectionnez le fichier docbook du répertoire fo de l’archive docbook-xsl-1.66.1 ; cela
vous permettra de fabriquer du XSL-FO à partir de DocBook (pour fabriquer du HTML, il vous faudra revenir ici et choisir le même fichier mais
dans le répertoire html).
2
– toujours dans cette fenêtre de transclipse, indiquez où se trouve l’archive
fop.jar : choisissez impérativement celle qui se trouve dans le répertoire
lib du dossier fop-0.20.5.
Configuration de votre environnement : pour voir ce qui se passe (notamment les inévitables erreurs de syntaxe, mais aussi les erreurs de configuration), ouvrez les vues Error Log et Problems (menu Window, sous-menu
Show View).
Choix de la perspective : aucune hésitation, vous devez choisir ... XML.
Vous voila (enfin !) prêt à rédiger ...
3
L’inévitable HelloWorld, en DocBook, tout seul,
dans mon coin
Commencez par créer un nouveau projet et choisissez-le dans XML > Project.
Donnez-lui un nom original (à vous de voir). Voila, déjà ça de fait. Maintenant,
créez un nouveau fichier XML, dans ce projet, en lui donnant un nom intéressant
(suffixé par .xml ). Là, il vous faut choisir la DTD que vous allez utiliser : choisissez le fichier docbookx.dtd, dans le répertoire où se trouve le contenu de
l’archive docbook-xml-4.2.zip. Cela vous donne accès à toutes les balises de
DocBook. Choisissez section comme racine de votre document. N’indiquez aucun Namespace. Cochez DTD in DOCTYPE et éventuellement corrigez le chemin
de la DTD (si ce chemin passe par un répertoire contenant un espace, alors
celui-ci est traduit par %20 et ça met la pagaille : remplacez-le par un espace
et tout devrait aller pour le mieux). Dans la dernière fenêtre, cochez Generate
< ?xml declaration.
Vous devriez obtenir un fichier XML, avec un début de DocBook dedans,
et notamment la balise racine de votre document, à savoir section. À vous
maintenant d’insérer quelque chose entre <section> et </section>.
Saisissez juste le début d’une nouvelle balise, à savoir <. L’éditeur syntaxique
devrait vous venir en aide, en vous proposant les balises candidates. Heureusement, il y en a peu ! Pour savoir pourquoi, rendez-vous dans le livre cité ci-dessus,
dans sa partie II, cliquez sur le lien section : là vous découvrez qu’une section
peut commencer par une sectioninfo, et qu’ensuite il faudra impérativement
un title (avec en option un subtitle, et/ou un titleabbrev). Donc tant
que vous n’aurez pas inséré une balise title, l’éditeur ne vous proposera rien
d’autre.
Choisissez donc pour l’instant une sectioninfo. Avec la même opération,
vous découvrez qu’en revanche cette fois-ci il y a beaucoup de candidats. Choisissez seulement author. Toujours pareil : vous découvrez tous les candidats.
Prenez firstname puis surname et inscrivez-y vos prénoms et noms, sans aller
voir les balises candidates, elles sont encore nombreuses.
Passez ensuite en-dessous de /sectioninfo, et insérez le fameux title.
Inscrivez ici la première phrase qui vous passe par la tête.
Passez ensuite en-dessous de /title et entrez la balise <para> (elle délimite
un paragraphe). Inscrivez ici la phrase choc : Hello World.
Enregistrez les modifications apportées à ce fichier. Puis, avec le menu contextuel associé à ce fichier (dans la vue Navigator), choisissez l’item (tout en bas)
3
Transform XML. Vous venez de franchir un grand pas : votre document DocBook
est en train de se transformer en XSL-FO. Vous ne voyez rien apparaitre ? Normal : il faut raffraichir le contenu de votre projet dans la vue Navigator : menu
contextuel associé au nom de votre projet. Miracle ! Vous pouvez maintenant
transformer ce nouveau fichier (qui contient du XSL-FO) en PDF, PostScript ...
Pour cela utilisez, dans le menu contextuel de votre fichier, puis dans le sousmenu Transform XSL-FO to, l’item de votre choix. Vous pouvez visualiser ce
deuxième nouveau fichier avec l’outil de votre choix, en dehors d’eclipse. Petits conseils : toujours sauvegarder son fichier avant de tenter une opération,
sinon l’opération risque d’être effectuée sur la version précédente du fichier, et
ne jamais oublier de fermer le fichier PDF (ou autre) qu’on vient d’admirer,
avant de tenter de générer un autre : le processus FOP doit détruire ce fichier
avant d’en faire un autre.
Vous pouvez aussi obtenir la même page, au format html, en allant changer
le fichier XSL utilisé (cf. chapitre Configuration d’eclipse ).
Pas mal ? ! Maintenant pouvez exercer votre curiosité en essayant d’inclure
dans le document des listes à puces : allez voir les balises <itemizedlist>,
<listitem>. Vous pouvez aussi ajouter <email> dans <author> de la <sectioninfo>.
Essayez <address> après </title>.
Si votre nom apparait plusieurs fois dans votre document, vous pouvez l’associer à une entité : pour cela allez à la fin de la ligne commençant par < !DOCTYPE
...>. Juste avant le > de la fin de ligne : insérez [< et regardez ce que vous propose l’éditeur. Choisissez < !ENTITY et entrez ceci :
< !ENTITY nom "Beaune">]
Là où vous écriviez votre nom, vous pouvez maintenant écrire plus simplement ’&nom ;’.
4
Mon premier vrai document, en DocBook, mais
toujours tout seul, dans mon coin
Le but maintenant est que chacun d’entre vous construise son propre CV de
son côté. Ensuite dans le chapitre suivant de ce TP, vous mettrez en commun
votre travail pour faire un recueil de tous ces CV.
Vous allez donc ouvrir un nouveau projet XML. Puisque le coeur de votre
document devra être utilisé aussi bien seul que dans un ouvrage collectif, vous
allez séparer votre travail en deux fichiers : l’un ayant pour racine la balise
section, et l’autre ayant pour racine la balise article.
Le premier fichier (section) contiendra votre CV. Le deuxième contiendra
des titres, auteurs, etc., et un appel au premier.
Le premier ne devra pas comporter l’entête < !DOCTYPE ...>. Si eclipse
l’ajoute automatiquement, alors supprimer-le. À l’intérieur de la section principale, ce premier fichier contiendra :
– une sectioninfo, avec auteur, email, etc.
– un titre (obligatoire)
– une adresse
– des sections (en fait <section> est récursif, et lorsqu’on inclut une section
dans une autre section, c’est une sous-section, et ainsi de suite ...
Les différentes sous-sections de votre CV pourront être : études antérieures,
4
exprériences en entreprises, axes choisis au premier semestre, axes souhaités
au second, thème de votre projet (activité ’conduite de projet’) de l’an passé,
activités dans des clubs, etc.
Si voulez faire une liste à puces avec par exemple des dates au lieu de simples
puces : allez voir la balise <segmentedlist>.
Dans le second fichier (dont la racine est article), vous devrez inclure :
– une entité pour désigner le premier fichier :
{<!ENTITY moncv SYSTEM "nomdufichier.xml">}
en indiquant bien le chemin absolu et complet du fichier nomdefichier.xml.
– d’autres entités si nécessaire
– un titre
– une rubrique articleinfo
– une rubrique warning où vous informerez le lecteur qu’il ne s’agit que d’un
brouillon, pas quelque chose d’abouti
– l’inclusion du premier fichier (en guise de section) : il suffit d’écrire
&moncv ;
– et enfin une rubrique ackno
Vous devez remarquer que le warning est justement annoncé par warning.
Qu’une Table of Contents apparait. Par terrible dans un papier en français !
Alors à la place de <article> vous allez tenter ceci :
<article lang="it">
C’est pas mieux ? Si vous voulez encore plus exotique vous pouvez essayer :
<article lang="ru">
, mais pas sûr que les polices de caractères soient trouvés.
Vous avez donc maintenant un pseudo CV. Passons au travail de groupe ...
5
Mon premier livre DocBook, dont je n’écris
qu’une partie
Ou comment supporter les erreurs des autres ...
Il va falloir s’organiser. Je vous propose de vous regrouper par sous-groupes,
entre collègues qui faites partie d’un même groupe pour les projets de l’axe,
tels que formés récemment. Chaque sous-groupe ainsi constitué va rédiger un
chapitre. Puis tous les chapitres seront regroupés dans un livre. Puisque vous
allez mettre en commun tous vos fichiers, autant se mettre d’accord au préalable
sur les noms de fichiers. La feuille CV créée précédemment doit avoir pour nom :
votre nom, suffixée par .xlm. Chaque groupe se construira un fichier contenant
son chapitre : ce fichier devra avoir pour nom : le nom du projet de l’axe ISI.
Le fichier global, regroupant le tout s’appellera CVaxeISI.xml.
Pour mettre en commun tout ces fichiers, vous allez utiliser la fonctionnalité
CVS d’eclipse. L’un d’entre vous (mais un seul) va donc créer le Repository :
dans le menu contextuel du projet, sous-menu Team, choisissez Share Project
... :
5
–
–
–
–
–
Host = pc-beaune.emse.fr
Repository path = /cvs
user = votre nom de famille (en minuscules, et tronqué à 8 lettres)
Password = (il n’y en a pas ; un peu dangereux, non ?)
Connection type : pserver (pas terrible car les mots de passe passent en
clair ; mais ici nous n’en avons pas ! !)
– cochez Save Passord (comme ça il ne vous le demandera plus ! ! !)
– acceptez le Commit et mettez un message indiquant qu’il s’agit de la
version initiale
Le Repository est créé. Les autres peuvent aller se connecter à ce Repository :
faites comme ci-dessus au début, mais dès la deuxième fenêtre choisissez ”Use
an existing module .... Vous devriez retrouvez le Repository créé par votre
collègue, ci-dessus. Surtout, ne choisissez pas CVSROOT : il contient des données
de gestion pour CVS. Jamais personne ne va trifouiller dans ce répertoire, au
risque de saccager le boulot de tout le monde.
Puis choisissez HEAD car aucune branche n’a encore été créée.
Dans la fenêtre qui apparait, CVS vous indique qu’il y a des conflits entre
votre projet et celui du Repository. Normal. Demandez (menu contextuel) à ce
qu’il ne tienne plus compte des conflits avec le fichier .project (Remove from
View) et faites un Commit... de votre fichier (celui contenant votre CV), et un
Update... de tous les fichiers que vos collègues ont déjà déposés.
Vous voila avec un projet (localement) qui contient votre création, et celles
de pas mal de vos collègues. Dans le Repository, il y a aussi ces mêmes fichiers. Il vous faudra faire un Update... dans quelques minutes, lorsque tous
vos collègues vous auront rejoints sur ce Repository.
Dans chaque groupe, il faudrait qu’un individu crée le fichier chapitre : il
faudrait lui donner un nom significatif (le nom du projet d’axe, par exemple).
Ce fichier contiendra les balises suivantes : chapter, avec un titre, et l’inclusion
des CV des membres du groupe.
Lorsque ce fichier est bien au point, il peut être déposé dans le Repository
(Commit). Les autres membres du groupe peuvent le charger (Checkout) et le
tester localement. Éventuellement un membre peut y apporter une modification
qui lui semble pertinente. Lorsqu’il est sûr que son fichier marche bien, il peut
tenter de le déposer (Commit). Éventuellement, il devra faire un Update si
quelqu’un a aussi, entre temps, changé ce même fichier. Remarquez l’évolution
des numéros de versions.
N’hésitez pas, lorsque vous allez dans la perspective CVS Repository Exploring
de faire un rafraichissement du module qui vous concerne (sinon, vous restez sur
d’anciennes informations, d’anciennes versions de fichiers).
Pour l’ensemble de la promo, il faudrait qu’un élève fasse le fichier CVaxeISI.xml.
Il devra contenir les balises : book (avec lang=”fr”), dedication (avec dedans un
title, un caution, un tip, un warning), un bookinfo (avec title, author, date), un
preface (avec title et para), puis l’inclusion des fichiers des groupes contenants
chacun un chapitre, et enfin, éventuellement un index.
Lorsque ce fichier est fait, et qu’il marche bien, il doit être déposé (Commit).
Chacun peut alors le charger (Checkout), le modifier si besoin, puis le déposer,
etc.
Au bout d’un moment, votre livre devrait se stabiliser.
En fait, on aurait pu s’organiser un peu mieux, en créant des répertoires dans
le module déposé dans CVS. Par exemple, un répertoire pour chaque groupe.
6
Et puis il reste encore à découvrir quelques fonctionnalités très utiles dans
CVS (les branches, les tags, les contraintes, etc.). Vous découvrirez tout ceci
au fur et à mesure que vous l’utiliserez. Une bonne documentation en ligne se
trouve à cette url :
– https://www.cvshome.org/docs/manual/
FIN
7