C.  Production de la version HTML de ce guide pratique

Ce court chapitre explique comment produire la version HTML de ce guide pratique sous Linux.

Ce chapitre explique quels outils utiliser, comment les installer et se termine par la commande permettant la production de la version HTML de ce guide pratique. La bibliothèque libxml2 et ses outils associés sont supposés installés sur votre machine. Les commandes nécessaire à la production des autres formats sont laissées en exercice pour le lecteur (^_^)

L'outil utilisé pour produire la version HTML de ce guide pratique est la version Java 2 de Xalan.

[Note]Note

Xsltproc, bien qu'il soit plus simple à utiliser, ne permet pas de produire une version complètement correcte de ce document. En effet, ce document utilise, dans un extrait de code, des icônes numérotées de renvois (callout). Le rendu de ces icônes n'est pas possible sans utiliser de bibliothèques d'extensions complémentaires, ce qui est notamment possible avec Xalan et Saxon.

Dans les étapes qui suivent, lorsque nous installerons de nouveaux outils, nous les installerons dans le répertoire ~/outils-docbook/, c'est-à-dire dans un sous-répertoire créé pour l'occasion dans votre répertoire personnel. Si vous êtes administrateur de votre machine, vous devrez extrapoler à partir de ces instructions d'installation afin de réaliser une installation globale accessible à tous vos utilisateurs.

Nous allons commencer par installer le DTD[2] XML DocBook. Téléchargez sur http://www.oasis-open.org/docbook/xml/4.5/ l'archive zip contenant le DTD et installez-le comme suit :

# Définition du répertoire cible de l'installation
CIBLE="$HOME/outils-docbook"

# Création du dossier où installer le DTD
mkdir -p "$CIBLE/docbook-xml-4.5/"

# Décompression de l'archive
unzip docbook-xml-4.5.zip -d "$CIBLE/docbook-xml-4.5/"

# Création d'un lien logique docbook-xml
cd "$CIBLE"
ln -s docbook-xml-4.5 docbook-xml

# Retour dans votre répertoire personnel
cd

Pour utiliser ce DTD, vous devrez modifier la variable d'environnement XML_CATALOG_FILES :

export XML_CATALOG_FILES="$HOME/outils-docbook/docbook-xml/catalog.xml $XML_CATALOG_FILES"

Cette commande devra être répétée à chaque nouvelle session. Pour simplifier les choses, ajoutez cette commande à vos scripts de production ou à vos scripts de début de session.

Il nous faut maintenant installer la feuille de style XSL utilisée pour transformer le XML DocBook en HTML. Téléchargez les feuilles de style XSL sur : http://docbook.sourceforge.net et installez-les comme suit :

# Décompression et installation de l'archive
tar -xvjf docbook-xsl-1.70.0.tar.bz2 -C "$CIBLE"

# Création d'un lien logique docbook-xsl
cd "$CIBLE"
ln -s docbook-xsl-1.70.0 docbook-xsl

# Installation de la feuille de style
cd docbook-xsl
sh install.sh

# Retour dans votre répertoire personnel
cd

Téléchargez la feuille de style personnalisée du Projet de documentation Linux (LDP) sur http://www.happy-monkey.net/docbook/ et installez-la comme suit :

# Décompresser l'archive
tar xvzf tldp-xsl-04MAR2005.tar.gz

# Recopier la feuille de style personnalisée du LDP
# avec la feuille de style XSL DocBook
cp -Rv tldp-xsl-04MAR2005/* "$CIBLE/docbook-xsl/"

Vous n'avez plus besoin de conserver le dossier tldp-xsl-04MAR2005/ après cela.

Nous allons maintenant télécharger et installer l'environnement d'exécution Java. Vous pourrez le télécharger sur le site de Sun : http://java.sun.com/javase/.

# Déplacez l'archive dans le répertoire d'installation
mv jre-1_5_0_06-linux-i586.bin "$CIBLE"

# Exécutez l'installation
cd "$CIBLE"
sh jre-1_5_0_06-linux-i586.bin

# Créez un lien vers la version courante de Java
ln -s jre1.5.0_06 jre

# Retour dans votre répertoire personnel
cd

Pour utiliser ce moteur d'exécution, vous devrez définir la variable d'environnement suivante :

export JAVA_HOME="$HOME/outils-docbook/jre"

Nous allons maintenant installer le logiciel Xalan lui-même. Ce logiciel est disponible sur http://xml.apache.org/xalan-j/index.html. Téléchargez la version binaire de Xalan-J 2.7.0 et installez-la comme ceci :

# Définition du chemin vers l'environnement d'exécution Java
JAVA_HOME="$CIBLE/jre1.5.0_06"

# Décompression de l'archive
tar xvzf xalan-j_2_7_0-bin.tar.gz

# Installation de Xalan dans l'environnement d'exécution Java
cd xalan-j_2_7_0/bin
cp xalan.jar xercesImpl.jar xml-apis.jar "$JAVA_HOME/lib/ext/"

# Retour dans votre répertoire personnel
cd

Une fois cette dernière étape faite, vous n'aurez plus besoin de conserver le dossier xalan-j_2_7_0.

Il ne reste plus qu'à produire la version HTML avec la commande appropriée :

# Répertoire d'installation des outils DocBook

OUTILS_DOCBOOK="$HOME/outils-docbook"

# Répertoire local d'installation de Java

JAVA_HOME="$OUTILS_DOCBOOK/jre"

# Répertoire d'installation des catalogues XML
#
# - Le premier correspond au catalogue du DTD XML
#   DocBook installé en local.
#
# - Le second correspond au catalogue des feuilles
#   de style XSL installées en local.

XML_CATALOG_FILES="$OUTILS_DOCBOOK/docbook-xml/catalog.xml $XML_CATALOG_FILES"

# Extensions Java des feuilles de style XSL écrites pour Xalan

EXTENSIONS_XALAN="$OUTILS_DOCBOOK/docbook-xsl/extensions/xalan27.jar"

# Feuille de style XSL personnalisée du Projet de documentation Linux

XSL_LDP_MONOHTML="$OUTILS_DOCBOOK/docbook-xsl/html/tldp-one-page.xsl"

# Production de la version HTML

$JAVA_HOME/bin/java -classpath "$EXTENSIONS_XALAN" \
    org.apache.xalan.xslt.Process \
    -IN "Petit-guide-du-traducteur.xml" \
    -OUT "Petit-guide-du-traducteur.html" \
    -XSL "$XSL_LDP_MONOHTML" \
    -PARAM "admon.graphics" "1" \
    -PARAM "use.extensions" "1" \
    -PARAM "callouts.extensions" "1"

En cas de problème, vous pouvez vérifier que votre installation est correcte avec la commande suivante :

# Répertoire d'installation des outils DocBook

OUTILS_DOCBOOK="$HOME/outils-docbook"

# Répertoire local d'installation de Java

JAVA_HOME="$OUTILS_DOCBOOK/jre"

# Extensions Java des feuilles de style XSL écrites pour Xalan

EXTENSIONS_XALAN="$OUTILS_DOCBOOK/docbook-xsl/extensions/xalan25.jar"

# Production de la version HTML

$JAVA_HOME/bin/java -classpath "$EXTENSIONS_XALAN" \
    org.apache.xalan.xslt.EnvironmentCheck

Une fois le document HTML créé, il ne vous reste plus qu'à récupérer la feuille de style CSS du projet Traduc.org http://tigreraye.org/style.css et les images correspondant aux icônes utilisées. Pour les installer, recopiez la feuille de style style.css et le dossier ~/outils-docbook/docbook-xsl/images/ au même endroit que le fichier HTML :

wget http://tigreraye.org/style.css
cp -Rv ~/outils-docbook/docbook-xsl/images .