mercredi, août 8 2007

Nouvelle version d'ABS : 5.0.05

Comme dit dans la news du site abs.traduc.org, deux fichiers ne sont pas encore traduit :

  • un script Bash (insertion-sort.bash)
  • et l'index (INDEX00.xml).

De toute façon, ce dernier me génère une erreur bizarre lorsque je génère la version PDF du manuel.

Enfin bon, en attendant, comme le principal intérêt de cette nouvelle version est cet index, la mise à jour a peu d'intérêt pour l'instant :) Malgré tout, pour les impatients, c'est ici.

dimanche, mai 21 2006

Encore des nouvelles du département...

Après impression, le format A6 est vraiment trop petit. J'ai donc opté pour le format 4"25 sur 6"875 (ce qui nous donne du 10cm de large sur 17 de hauteur), le format des « Précis et concis » d'O'Reilly. Je gagne une centaine de pages :)



Pour en gagner un peu plus, j'ai essayé de supprimer le saut de page entre chaque page man. Malheureusement, même avec un refentry.pagebreak à 0, j'ai toujours un saut de page. J'ai fini par me demander si cela ne venait pas de ma version de docbook-xsl étant donné que je me traîne toujours la 1.68. J'ai donc utilisé la toute nouvelle version 1.70. J'ai eu droit à un joli message d'erreur. J'essaie donc la 1.69. De nouveau, un message d'erreur. Après quelques recherches dans Google, je finis par comprendre qu'il me faut utiliser une autre version que la 1.1.15 d'xsltproc. Donc, c'est parti : téléchargement/compilation/installation de libxml (dépendance de libxslt), et pareil pour libxslt. Rapidement, ça donne ceci :

wget http://ftp.gnome.org/pub/GNOME/sources/libxml2/2.6/libxml2-2.6.24.tar.bz2
tar xvfj libxml2-2.6.24.tar.bz2
cd libxml2-2.6.24
./configure --prefix=/opt/libxml2-2.6
make
sudo make install
wget http://ftp.acc.umu.se/pub/GNOME/sources/libxslt/1.1/libxslt-1.1.16.tar.bz2
tar xvfj libxslt-1.1.16.tar.bz2
cd libxslt-1.1.16
./configure --with-libxml-prefix=/opt/libxml2-2.6 --prefix=/opt/libxslt-1.1.16
make
sudo make install

Après un « export PATH=/opt/libxslt-1.1.16/bin:$PATH », « make quickpdf » ne me génère plus d'erreurs, j'ai bien mon PDF et je n'ai plus les sauts de page :)

Passons à la suite. J'ai ajouté le document d'installation, il faudra donc que j'utilise le profile standalone. J'ai aussi ajouté le tutoriel. J'ai supprimé les balises part, je n'utilise que des chapter pour gagner de la place. Ça commence à avoir une belle tête... enfin, à prendre forme plutôt car joli n'est pas le mot. Je vais avoir encore pas mal de bidouillage à effectuer pour avoir quelque chose de propre.

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 :)

lundi, mai 1 2006

Césure et alignement

J'avais quelques soucis avec fop lorsque je voulais qu'il utilise la césure. Il ne trouvait pas un fichier pour la césure française. Cette discussion m'a mis sur la piste. En fait, il faut télécharger un fichier jar supplémentaire. Ce fichier est proposé par un projet sourceforge nommé offo. Comme l'indique la page d'installation, il faut télécharger ce paquet, le décompresser et déplacer le fichier jar (fop-hyph.jar) dans $FOP_HOME/lib.

Une fois ceci intégré et l'option de césure activée (<xsl:param name="hyphenate">true</xsl:param>), j'ai pu générer le manuel PostgreSQL en PDF et avec césure. J'ai testé deux versions :

Je n'arrive pas à me décider sur le bon. L'alignement à gauche fait que ce n'est pas aligné à droite, ce qui est moche. Le justifié est bien aligné à gauche comme à droite mais me change la taille des espaces ce qui est très moche dans les tableaux. Et je ne sais même pas ce que demande la typographie française.

samedi, avril 29 2006

PostgreSQL manual in PDF

We have three major releases of the PostgreSQL manual in french : 7.4, 8.0 and 8.1. They are all written in SGML Docbook. We use openjade to convert thems in HTML files, and htmldoc to convert the big HTML file in PDF.

Three weeks ago, friends start talking about migrating to XML Docbook. They mostly did it. I just had some mistakes and a few tags to fix. This done, we used LFS makefile and XSLT files to build the HTML manual. It worked great. But then I told to myself that I should look into building a better PDF manual. htmldoc did a great job with the HTML file we provide but the result was kind of ugly. So I started working on it : fixing some issues in the XML files, adding icons, updating the XSL filters, upgrading FOP.

It took me two weeks to create this PDF manual but I'm very proud of it.

jeudi, avril 27 2006

Améliorations du jour

En dehors des corrections habituelles (qui devraient être terminées maintenant), j'ai fait quelques modifications sur la façon de générer le PDF :

  1. ajout des numéros de page dans les références internes (ce qui facilite la recherche une fois imprimé) ;
  2. ajout d'un en-tête (titre de la première section de la page et numéro de page) et d'un bas-de-page (numéro de page) avec un trait les délimitant du corps de la page ;
  3. suppression du saut de page entre chaque section (ce qui nous fait gagner la bagatelle de 300 pages !).

Évidemment, il me reste deux/trois trucs à régler :

  1. numéro des notes de bas de page ;
  2. l'en-tête est sympa mais j'aimerais avoir à la place de « The PostgreSQL Global Development Group » le nom du chapitre, le nom de la section ou le nom de la commande référencée ;
  3. logo PostgreSQL en fond de la toute première page ;
  4. supprimer l'alignement justifié (certainement un faux ami de justify), le remplacer par un alignement à gauche et une césure française (quelques pistes pour la gestion de la césure qui risque de ne pas être simple).

Bon, OK, en fait, ils sont quatre :)

mercredi, avril 26 2006

Quelques améliorations sur le PDF de PostgreSQL

Maintenant que j'arrive à le générer, j'essaie d'améliorer le rendu et de supprimer les messages d'avertissement qui apparaissent un peu partout.

Tout d'abord, dans les balises contenant des commandes à saisir (<screen>, <literallayout>, <programlisting>, <synopsis>), j'ai une première ligne vide. C'est assez désagréable visuellement principalement parce que c'est très visible : le fond est gris pour le contenu de ces balises. Le problème est dû à l'écriture du XML, en voici un exemple :

<screen>
createdb ma_base
[... etc ...]

La solution est simple : supprimer le retour chariot entre <screen> et la première ligne du contenu. On obtient donc ceci :

<screen>createdb ma_base
[... etc ...]

C'est pas très amusant à faire et c'est très très long. Je ne connais pas de moyen d'automatiser cela... si vous en trouvez un, n'hésitez pas à me prévenir par un petit message dans les commentaires.

J'ai eu aussi un autre problème bien gênant. Une commande ou le résultat d'une commande ne tient pas forcément sur une ligne. Dans le cas des balises décrites précédemment, il n'y a pas de retour à la ligne automatique. J'ai donc commencé par modifier ces commandes manuellement mais j'ai fini par trouver une astuce bien intéressante. En ajoutant

<xsl:attribute-set name="monospace.verbatim.properties">
  <xsl:attribute name="wrap-option">wrap</xsl:attribute>
</xsl:attribute-set>

mon problème n'existe plus. J'ai essayé la deuxième astuce qui permet d'ajouter un caractère indiquant un saut de ligne qui n'aurait pas dû exister mais je n'ai pas réussi à le faire fonctionner. Je tenterai de nouveau plus tard.

Le dernier problème que j'ai concerne les tableaux. Sans indication supplémentaire, FOP crée des colonnes de taille égale. Donc, si vous avez cinq colonnes, quelque soit leur contenu, elles disposeront chacune de 1/5 de la largeur du tableau. Difficilement acceptable. Il suffit d'ajouter une information dans la déclaration du tableau pour que la taille des colonnes soit modifiée. Par exemple, avec

<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col2" colwidth="2*"/>
<colspec colnum="3" colname="col3" colwidth="1.5*"/>
<colspec colnum="4" colname="col4" colwidth="1*"/>

La première colonne aura 18% de la largeur du tableau, la deuxième 36, la troisième 27 et la dernière 18.

Cela représente beaucoup de modifications manuelles, de générations, de vérifications... et on recommence :)

Cela étant dit, le résultat est très positif.

mardi, avril 25 2006

Et un PDF complet...

J'ai réussi à générer le PDF du manuel de PostgreSQL lundi matin. En effet, j'ai compris mon erreur : dans charset.sgml, le fichier déclarait un tableau de deux colonnes (tgroup cols="2") alors qu'il en comportait réellement cinq. En remplaçant le 2 par un 5, tout fonctionne. En fait, j'ai tout bêtement procédé par dichotomie. J'ai supprimé toutes les parties sauf la première, j'ai généré. Pas d'erreur, donc j'ai remis la deuxième partie, j'ai regénéré... en ainsi de suite jusqu'à trouver l'erreur.

Évidemment, il faut rendre le document PDF plus présentable. Actuellement, il fait 1700 pages et quelques et il n'est pas agréable à utiliser. J'ai donc passé une partie de ma soirée à essayer d'embellir le document. J'ai commencé en diminuant la taille de la police de deux points, ce qui m'a fait gagner 300 pages. J'imprimerais une page ou deux demain au boulot pour voir si cela reste lisible. Je pourrais même décider de réduire encore un peu.

Je dois aussi corriger tous les textes qui n'apparaissent plus, vérifier si je peux spécifier les tailles de certaines colonnes, corriger les erreurs non fatales, etc.

mercredi, avril 19 2006

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