Génération du manuel

Le manuel est écrit en SGML DocBook. Ce codage permet de spécifier les chapitres, les paragraphes. Un programme supplémentaire est nécessaire pour transformer ces fichiers source en des fichiers lisibles. Il en existe plusieurs : jade, openjade, etc. Ils s'occupent de générer les documents finaux en plusieurs formats : texte, HTML, PDF, PS, etc. Pour faciliter le travail, l'équipe de traduction française a décidé de passer à un format pratiquement identique mais bien plus pratique, XML DocBook. En effet, l'outil de génération, xsltproc, est beaucoup mieux maintenu qu'openjade et ses confrères.

Les documents sont donc écrits en XML. Des feuilles de style XSLT permettent de traduire les documents dans un format spécifié à xsltproc.

Voici les étapes nécessaires pour installer les outils qui vous permettront de générer le manuel de PostgreSQL sur votre poste.

Installation des feuilles de style XSLT

Il vous faut télécharger les feuilles de style XSLT. Nous ne conseillons pas les versions 1.70.0 et 1.70.1 qui semblent avoir un bug bien gênant pour nous. Nous utilisons actuellement la 1.69.1. Une fois téléchargé, placez-vous dans le répertoire /opt et déballez l'archive :

cd /opt
wget http://surfnet.dl.sourceforge.net/sourceforge/docbook/docbook-xsl-1.69.1.tar.bz2
tar xvfj docbook-xsl-1.69.1.tar.bz2

Si vous êtes sous debian/ubuntu, le paquets sont les suivants :

apt-get install docbook docbook-doc docbook-xsl docbook-xml
ln -s /usr/share/xml/docbook/stylesheet/nwalsh/ /opt/docbook-xsl

Pour que le fichier Makefile et les feuilles de style personnalisées du projet de traduction fonctionnent, il vous faut créer un lien symbolique entre ce nouveau répertoire et docbook-xsl (vous pouvez aussi renommer le répertoire créé par le déballage).

ln -s docbook-xsl-1.69.1 docbook-xsl

Pour plus d'informations, visitez le site du projet DocBook. Vous pouvez aussi lire DocBook XSL : The Complete Guide, la référence sur le XSL.

xsltproc

xsltproc est l'outil qui va transformer les fichiers XML DocBook en XHTML ou en FOP.

Il vous faut tout d'abord télécharger libxml2. Nous utilisons la version 2.6 mais, contrairement aux feuilles de style XSLT, nous n'avons pas de version à déconseiller.

wget ftp://xmlsoft.org/libxml2/libxml2-sources-2.6.26.tar.gz
tar xvfz libxml2-sources-2.6.26.tar.gz
cd libxml2-sources-2.6.26
./configure --prefix=/opt/libxml2-2.6
make
sudo make install

Vous avez donc installé une bibliothèque utilisée par xsltproc. Maintenant, nous allons construire cet outil :

wget ftp://xmlsoft.org/libxml2/libxslt-1.1.17.tar.gz
tar xvfz libxslt-1.1.17.tar.gz
cd libxslt-1.1.17
./configure --prefix=/opt/libxslt-1.1 --with-libxml-prefix=/opt/libxml2-2.6
make
sudo make install

fop

fop est un outil de génération de document, écrit en Java... donc, il faut commencer par installer un JRE. Je n'ai eu aucun état d'âme à installer la JRE de Java (avant même qu'ils ne la « libèrent ») mais vous pouvez très bien utiliser une autre JRE (un test avec libgcj montre que cela fonctionne sans soucis). Normalement, la JRE de Java doit être maintenant dans unstable. Sinon, vous pouvez comme moi ajouter deb ftp://ftp.tux.org/java/debian/ sarge non-free dans votre fichier /etc/apt/sources.list, mettre à jour vos listes avec apt-get update et enfin installer la JRE avec apt-get install j2re1.3. Pour plsu d'informations, voir un article de BxLUG.be.

Installation de FOP

Génération

Dans les sources du manuel traduit, nous avons placé un Makefile qui vous permettra de générer automatiquement une version du manuel dans un certain format. Voici les cibles possibles du Makefile :

• html : construction des fichiers HTML (identique à la version 8.1 du site de traduction) ;
• pdf : construction du manuel au format PDF ;
• manpages : construction des pages man ;
• htmlhelp : construction de pages HTML qui pourront être assemblées en un fichier CHM, le standard du fichier d'aide sous Windows ;
• INSTALL.txt et INSTALL.html : construction du fichier d'installation de PostgreSQL respectivement au format texte et HTML.

Autrement dit, un make pdf construira uniquement le fichier PDF alors qu'un make INSTALL.txt génèrera le document d'installation de PostgreSQL au format texte.

Il existe une dernière cible qui construit toutes les cibles : all. Un simple make all et vous devriez vous retrouver avec tous les formats générés :)

Dernière info : la génération crée un répertoire pgsql-<version>-fr à la base de votre répertoire personnel. Actuellement, il s'agira de ~/pgsql-8.1.4-fr.