samedi, mai 13 2006

Passage d'ABS du SGML DocBook au XML

J'en avais discuté avec Balise et fevrier lors des Solutions Linux 2006. J'ai fini par le faire. J'avais peur que ce soit super galère mais cela a été assez simple finalement. J'ai bossé dessus deux demi-journées seulement. Le seul point qui m'a donné du fil à retordre concerne l'inclusion des scripts shell. Ils ne sont pas en XML, ils comportent des caractères interdits... un vrai bonheur :)

Au lieu d'utiliser les entités, je suis passé par XInclude. Un article sur XML.com offre une excellente introduction. Le point intéressant se trouve pratiquement en fin de page. L'auteur indique qu'il est possible d'insérer un fichier non XML et qui ne sera pas analysé par xsltproc. Pour cela, il faut ajouter la ligne suivante :

<xi:include parse="text" href="ton_fichier.sh" />

parse="text" fait en sorte qu'il ne prend pas le fichier pour un autre fichier XML à analyser. Du coup, je peux insérer mes scripts sans soucis.

Bref, le XML est syntaxiquement correct et valide. J'ai ajouté une copie du Makefile et des feuilles de style XSLT. Je génère une version HTML et PDF avec un simple make all.

Tous mes projets de traduction sont en XML maintenant. Youhou :)

dimanche, mai 7 2006

Manuel de PostgreSQL, le retour

Après avoir expliqué rapidement ce que l'équipe de traduction française avait réussi à faire suite au passage du SGML au XML, j'ai remarqué qu'il me manquait les solutions à deux problèmes pour faire de même avec la documentation originale.

Tout d'abord, la documentation originale comprend des insertions conditionnelles. En effet, le chapitre d'installation est aussi un document spécifique généré pour être inclus dans le package des sources de PostgreSQL. Ce fichier contient le mot document quand il fait partie de la génération du fichier INSTALL et contient le mot chapitre quand il fait partie de la génération complète du manuel. Parfois, ce sont des sections entières qui sont intégrées ou ignorées. Comment faire pour obtenir le même résultat en XML Docbook ? Il existe un moyen simple : les attributs de profile. Il existe des attributs standards comme os. En indiquant <para os="linux">linux-2.6.16</para><para os="windows">Windows XP</para>, vous obtiendrez un paragraphe contenant le texte « linux-2.6.16 » avec le profile os=linux et vous obtiendrez un paragraphe contenant le texte « Windows XP » avec le profile os=windows. Sans profile, vous n'aurez pas de paragraphe. Vous pouvez aussi créer des attributs personnalisés. Comme aucun des standards ne me convenait, j'ai créé un attribut que j'ai ajouté à chaque élément conditionnel. Vous trouverez ici la liste des modifications. J'arrive donc maintenant à générer un document autonome concernant l'installation.

Mon deuxième problème est la génération des pages man. Je n'ai pas encore terminé mais j'ai réussi à générer une page man... pas très belle, mais elle se génère. Toutes les infos sont disponibles ici grâce à l'excellent « Guide complet de Docbook XSL », malheureusement en anglais. Il serait temps qu'il se trouve un traducteur :)

mercredi, avril 19 2006

Suite de mes aventures dans le beau monde de XSLT et FOP

J'ai fini par comprendre le problème de l'erreur du make pdf d'hier. Voici comment je suis arrivé à générer un PDF avec fop...

Le fichier .fo généré par xsltproc est un peu bordélique. J'ai donc commencé par ranger les balises une par une avec la commande sed suivante :

sed 's/>/>
/g' lfs-pdf.fo > lfs-pdf2.fo

L'erreur étant internal-destination or external-destination must be specified in basic-link, j'ai recherché tous les basic-link du fichier .fo :

grep "basic-link" lfs-pdf2.fo

ce qui me donne à peu près ceci

[... j'en coupe une grosse partie ...]
<fo:basic-link internal-destination="ch-system-pwdgroup">
</fo:basic-link>
<fo:basic-link internal-destination="ch-system-man-pages">
</fo:basic-link>
<fo:basic-link internal-destination="">
description</fo:basic-link>

Le dernier internal-destination est bien vide. Comme il ne contient rien de bien intéressant, j'ai supprimé toute la cellule, à savoir les lignes suivantes :

<fo:table-cell>
<fo:block>
<fo:basic-link internal-destination="">
description</fo:basic-link>
</fo:block>
</fo:table-cell>

La génération ne pose plus aucun problème ! J'ai un superbe PDF pour LFS que vous pouvez voir sur le site de la traduction de LFS (superbe dans le sens joli et utilisable... en effet, les liens sont disponibles, les numéros de page sont exacts... un vrai bonheur). Très content, je me suis mis en tête de faire celui du manuel de PostgreSQL. Je modifie un peu le script Makefile pour tenir compte des spécificités de ce manuel. Malheureusement, j'obtiens une erreur bien gênante :

Exception in thread "main" java.lang.OutOfMemoryError

Y compris après avoir modifié FOP_OPTS pour lui donner 1 Go de mémoire, rien à y faire, il s'arrête à la page 252.

Google me dit gentiment de changer de processeur FO... mouais, me suis déjà embêté à installer celui-là. Les autres sont soit propriétaires soit non disponibles via apt-get... pfff. Je testerais ce soir la génération d'un fichier HTML complet que je balancerais à html2ps, puis ps2pdf.

Suite du passage en XML : génération HTML et PDF

Maintenant que xsltproc génère sans erreur, il est temps de se pencher sur la qualité de la génération. Je souhaite avoir à peu près le même rendu qu'avec openjade. Commençons par le HTML. J'ai utilisé le fichier stylesheets.xsl du répertoire des sources du manuel de PostgreSQL. J'ai simplement mis en commentaire la ligne spécifiant l'emplacement réseau des feuilles de style XSLT de base. Je préfère utiliser celles dont je dispose en local. J'ai donc ajouté une ligne pour pointer vers le bon répertoire. Ensuite, j'ai récupéré le Makefile du projet de traduction LFS et je l'ai légèrement modifié. Voici le contenu simplifié :

BASEDIR=~/lfs-book
DUMPDIR=~/lfs-commands
CHUNK_QUIET=0
PDF_OUTPUT=LFS-BOOK.pdf
NOCHUNKS_OUTPUT=LFS-BOOK.html
XSLROOTDIR=/usr/share/xml/docbook/xsl-stylesheets-current
html:
       xsltproc --xinclude --nonet \
         -stringparam profile.condition html \
         -stringparam chunk.quietly $(CHUNK_QUIET) \
         -stringparam base.dir $(BASEDIR)/ \
         stylesheet.xsl postgres.sgml

On voit d'ailleurs que je n'ai pas vraiment tout modifier (les noms de variable font furieusement penser à LFS :-) ). Un simple make html me génère la documentation au format HTML avec de nombreux fichiers. Pour être franc, c'est super long... mais c'est bien meilleur, notamment avec la création d'un index. Pour ceux qui veulent voir le résultat, c'est ici.

Ensuite, j'ai essayé de générer un PDF. Alors là, c'est galère. J'ai installé fop après avoir déclaré un dépôt non libre dans mon /etc/apt/sources.list :

deb ftp://ftp.tux.org/java/debian/ sarge non-free

Voir ce document pour plus d'infos. Après ça, j'ai récupéré Jimi pour le traitement des images à intégrer dans le PDF. Oui, je sais, le manuel de PostgreSQL ne contient aucune image... sauf que la génération des documents HTML importe des images pour les notes, avertissements, etc. Ceci fait, j'ai pu lancer la génération du PDF avec cet ajout dans le Makefile :

pdf:
       xsltproc --xinclude --nonet --stringparam profile.condition pdf \
               --output $(BASEDIR)/lfs-pdf.xml stylesheets/lfs-profile.xsl index.xml
       xsltproc --nonet --output $(BASEDIR)/lfs-pdf.fo stylesheets/lfs-pdf.xsl \
               $(BASEDIR)/lfs-pdf.xml
       fop $(BASEDIR)/lfs-pdf.fo $(BASEDIR)/$(PDF_OUTPUT)
       rm $(BASEDIR)/lfs-pdf.xml $(BASEDIR)/lfs-pdf.fo

Évidemment, ça devait bien planter à un moment. C'est maintenant avec ce joli message d'erreur :

[ERROR] file:/home/guillaume/lfs-book/lfs-pdf.fo:4040:429972 internal-destination or external-destination must be specified in basic-link

Et là, je suis perdu. Je ne trouve rien de bien intéressant dans Google. Les fichiers générés ne m'apportent rien. Aucune idée. Je ferais mieux d'aller me coucher...

dimanche, août 22 2004

LFS : chapitres 5 et 7 traduits :)

Pendant que la copie se fait, voici un petit compte-rendu de la journée. Ce matin a tranquillement débuté avec la traduction du chapitre 5 de LFS-5.1.1. Tout n'a pas été fini avant le déjeuner mais une bonne partie était quand même réalisée. Après manger, j'ai jeté un œil sur ce qui m'attendait pour le chapitre 6... une horreur, pratiquement rien de récupérable. À part deux/trois fichiers, tout est à refaire. J'ai donc préféré attaquer le chapitre 7, terminer les quelques fichiers qui me restaient dans certains chapitres et faire le point sur le chapitre 6.

Le chapitre 6 est le seul qui me reste... environ 60 fichiers qui vont me prendre une bonne partie de ma semaine. Moi qui voulais mettre à jour le guide pratique Plug-And-Play, ce ne sera pas pour tout de suite...

Ce soir, j'ai regardé les modifications apportées au processus de génération des versions XHTML et PDF. Manuel a fait un énorme travail sur les feuilles de style XSLT. C'est impressionnant. Il a aussi ajouté des scripts de génération. Du coup, un simple « make /home/guillaume/LFS » me génère la version HTML dans le répertoire précisé en premier argument, copie les images et les feuilles de style CSS. Non, vraiment, du travail de pro. Vous pouvez juger par vous-même avec cette première version de la traduction française. Vous pouvez remarquer qu'il manque certaines entités, notamment &nbsp; (espace insécable) ainsi que &oelig; (« œ ») et que le texte souffre encore de quelques erreurs. Attendez-vous à une demande de relecture d'ici la fin de la semaine :)

mercredi, août 18 2004

fetchmail authentication OK on guillaume@belgarath.linuxfromscratch.org

Enfin :)

Je ne pouvais plus récupérer mes mails sur la machine linuxfromscratch.org depuis au moins cinq-six jours. Et Gerard a corrigé cela (ne me demandez pas comment, il n'a pas fait trop de commentaires). Je peux enfin lire les mails provenant des différentes listes de diffusion sur LFS.

Cela tombe bien. Je voulais savoir si la version 6.0 allait bientôt sortir. Cela ne semble pas le cas, je vais donc pouvoir consacrer un peu de temps à la traduction de LFS-5.1.1. Apparemment, beaucoup de fichiers ont changé... du travail en perspective ! En attendant, le travail sur la version 6.0 semble bien avancé. Manuel Canales a sorti une version couleur du PDF. Bluffant ! Ce type semble très doué pour la génération via des feuilles de style XSLT.

Je vais déjà commencer avec la version 5.1.1... allez, du courage :)