A. Patron DocBook

Ce patron présente un exemple commenté de l'en-tête d'un document XML DocBook. Il reprend tous les éléments de l'en-tête d'une traduction française placés dans leur contexte.

<?xml version="1.0" encoding="iso-8859-15"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY howto      "http://www.traduc.org/docs/howto/lecture/">
<!ENTITY guide      "http://www.traduc.org/docs/guides/lecture/">
<!ENTITY traduc     "http://www.traduc.org">
]>

<article lang="fr">

<articleinfo>

  <!--
      Merci à Simon Depiets qui a réalisé la version initiale de
      ce patron.
   -->


  <!-- Titre et sous-titre -->

  <!--
      Si vous voulez être sûr que votre document soit lu,
      assurez-vous que le titre français du document soit
      simple, clair et compréhensible. Garder le titre
      original n'est en général pas un bon choix.
    -->

  <title>

     Petit guide d'exemple de structure XML DocBook

  </title>

  <subtitle>
  
     Version française du <foreignphrase lang="en">DocBook 
     Structure Example Mini-HOWTO</foreignphrase>
  
  </subtitle>

  <!--
      On conserve toujours la mention du titre original en
      sous-titre afin de rendre le document plus facile à trouver
      par une recherche réalisée à partir du titre original.
   -->
  

  <!-- Version et date de la version française -->
  
  <releaseinfo>Version&nbsp;: 0.6.fr.1.0</releaseinfo>  

  <pubdate>1er août 2004</pubdate>

  <!-- 
      La date du document doit être en clair (i. e. en français)
   -->


  <!-- Auteurs, traducteurs et relecteurs -->

  <author>
     <firstname>Jeffrey</firstname>
     <surname>Sinclair</surname>
     <email>jeff CHEZ bab POINT com</email>
  </author>

  <othercredit role="traduction" class="translator">
     <firstname>Brice</firstname>
     <surname>Le Creurer</surname>
     <contrib>Adaptation française</contrib>
     <email>brice CHEZ grandcroix POINT net</email>
  </othercredit>

  <othercredit role="relecture" class="translator">
    <firstname>Alice</firstname>
    <surname>Martin</surname>
    <contrib>Relecture de la version française</contrib>
    <email>alice CHEZ ouebe POINT org</email>
  </othercredit>


  <!-- Historique des révisions -->

  <revhistory>

    <revision>
      <revnumber>0.6.fr.1.0</revnumber>
      <date>2004-08-01</date>

      <!--
          Les dates de l'historique des révisions doivent
          utiliser le format Iso : « aaaa-mm-jj » avec
          aaaa = année sur 4 chiffres,
          mm = mois sur 2 chiffres et
          jj = jour sur 2 chiffres.
        -->

      <authorinitials>BLC, AM</authorinitials>
      <revremark>Première traduction française.</revremark>
    </revision>

    <revision>
      <revnumber>0.6</revnumber>
      <date>2003-06-17</date>
      <authorinitials>JS</authorinitials>
      <revremark>

          Quelques corrections pour que le document aie une
          structure valide. <emphasis lang="en">Some
          fixes to get a valid document structure.</emphasis>

          <!--
              Si la licence l'exige — c'est par exemple le cas de
              la licence de documentation libre GNU (GFDL) —
              il est nécessaire de conserver une copie du texte de 
              l'historique des révision en version originale.
           -->
    
      </revremark>
    </revision>
    
    <revision>
      <revnumber>0.4</revnumber>
      <date>2002-02-20</date>
      <authorinitials>JS</authorinitials>
      <revremark>

          Version initiale. <emphasis lang="en">Initial 
          revision.</emphasis>

      </revremark>
    
    </revision>

  </revhistory>


  <!-- Résumé du document -->   

  <abstract><para>
    
      Ce document est un document d'exemple donnant la structure
      de base d'une traduction française rédigée selon le format
      XML DocBook. Ce document n'est pas intéressant en lui-même.
      Tout son intérêt tient en son code source (^_^).
    
      <!--
          Ce résumé doit être clair et pouvoir être compris hors
          du contexte du document
        -->

  </para></abstract>

</articleinfo>

<section>
  <title>
      Commentaires et corrections
  </title>

  <para>

       Merci de faire parvenir en anglais à l'auteur vos questions
       et commentaires relatifs à la version originale de ce
       document à l'adresse

       <email>jeff CHEZ bab POINT com</email>.

  </para>
  <para>

      N'hésitez pas à faire parvenir vos commentaires et suggestions
      concernant l'adaptation française de ce document au projet
      <ulink url="&traduc;">Traduc.org</ulink> à
      l'adresse&nbsp;:

      <email>commentaires CHEZ traduc POINT org</email>.

  </para>
</section>

<section>

  <title>
      Nouvelles versions de ce document
  </title>

  <para>

      Vous trouverez la plus récente version française de ce document à
      l'adresse&nbsp;: <ulink url="&howto;patron.html"/>.

  </para>

  <para>
      
      La plus récente version originale de ce document est disponible à
      l'adresse&nbsp;: <ulink
      url="http://www.tldp.org/HOWTO/patron.html"/>.
  
  </para>
</section>

<section>

  <title>
      Reste du document
  </title>

  <para>

      Bla bla bla bla bla bla bla bla bla bla bla bla bla bla
      bla bla bla bla bla bla bla bla bla bla bla bla bla bla
      bla bla bla bla bla bla bla bla bla bla bla bla bla bla
      bla bla bla bla bla bla bla bla bla bla bla bla bla bla
      bla bla bla bla bla bla bla bla bla bla bla bla.

  </para>

  <para>

      Bla bla bla bla bla bla bla bla bla bla bla bla bla bla
      bla bla bla bla bla bla bla bla bla bla bla bla bla bla
      bla bla bla bla bla bla bla bla.

  </para>

  <para>

      Bla bla bla bla bla bla bla bla bla bla bla bla bla bla
      bla bla bla bla bla bla bla bla bla bla bla bla bla bla
      bla bla bla bla bla bla bla bla bla bla bla bla bla bla
      bla bla bla bla.

  </para>

</section>

</article>

B.  Produire simplement une version HTML d'un document XML DocBook

Vous devez disposer des paquets suivants^[8] :

Pour produire une version HTML, vous devrez simplement indiquer à xsltproc l'emplacement de la feuille de style utilisée (appelée xhtml/docbook.xsl) et le nom du fichier source XML :

xsltproc feuille_de_style.xsl document.xml > document.html

Par exemple, chez moi, j'utilise la commande suivante :

FEUILLE_DE_STYLE="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl"
xsltproc "${FEUILLE_DE_STYLE}" document.xml > document.html

Et voilà ! C'est fini. Vous disposez maintenant d'une version HTML de votre document.

Il est possible d'améliorer le rendu du document produit en utilisant certaines options de la feuille de style XSL DocBook. Du fait de l'ajout de ces options, la ligne de commande peut devenir un peu longue. Pour simplifier, j'ai donc préparé un petit script qui rassemble toutes les options que j'utilise.

#!/bin/bash

# On s'arrête en cas d'erreur

set -e

# Vérification du nombre de paramètres

if [ "$#" -ne 1 ] ; then

    echo
    echo "Script de production d'une version HTML d'un document XML DocBook."
    echo
    echo "Utilisation :"
    echo "$(basename $0) document.xml"
    echo
    exit 1

fi

# Définition des fichiers à utiliser

SOURCE_XML="$1"
DOCUMENT_HTML="${1%.xml}.html"

# Feuille de style XSL (à personnaliser)

FEUILLE_DE_STYLE_XSL="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl"

# Vérification de l'existence du document XML source

if [ ! -f "${SOURCE_XML}" ] ; then

    echo
    echo "Erreur : fichier ${SOURCE_XML} introuvable !"
    echo
    exit 1

fi

# Vérification de la structure du document

echo "Vérification de la structure de ${SOURCE_XML}"

xmllint --valid --noout "${SOURCE_XML}"

# Production de la version HTML

echo "Production de la version HTML de ${SOURCE_XML}"

xsltproc --stringparam "admon.graphics" "1" \
         --stringparam "html.stylesheet" "style.css" \
         --stringparam "css.decoration" "0" \
         --stringparam "blurb.on.titlepage.enabled" "1" \
         --stringparam "contrib.inline.enabled" "0" \
         --stringparam "make.valid.html" "1" \
         --stringparam "make.year.ranges" "1" \
         --stringparam "html.cleanup" "1" \
         --stringparam "section.autolabel" "1" \
         "${FEUILLE_DE_STYLE_XSL}" "${SOURCE_XML}" \
         > "${DOCUMENT_HTML}"

echo "Terminé"

C.  Production de la version HTML de ce guide pratique

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

D.  Aide-mémoire des licences libres

Attention !

Cet aide-mémoire ne vous dispense pas de lire complètement la licence d'un document avant d'en commencer la traduction ! Lire la licence d'un document vous permettra de connaître les conditions selon lesquels un document peut être traduit et sa traduction diffusée. La traduction d'un document est une version modifiée de sa version originale. Donc une licence interdisant la diffusion d'une version modifiée interdit également d'en diffuser une traduction !

E. Licence Art libre