DocBook – Installation et utilisation de base | Tutorials for building software

Cet article: Installation et utilisation de base.

Pré-requis: Connaissance de base de XML et ses feuilles de style XSL. Une connaissance des principes suffit.

Installation sur un système Ubuntu/Debian ou compatible.

Pour une installation minimale qui permet de générer des documents au format html et pdf, exécuter:

sudo apt-get install xsltproc fop docbook-xsl

Cette commande installe les trois paquets:

xsltproc : Processeur de feuilles de styles XSLT
fop: Moteur de transformation au format PDF.
docbook-xsl: ensemble de feuilles de syle xsl du système DocBook. Cet ensemble est installé dans: /usr/share/xml/docbook/stylesheet/nwalsh/

Création du document.

Le contenu du document à créer doit être saisi au format XML en respectant le formalisme DocBook. Ce formalisme est constitué par un ensemble de balises XML organisées selon une structure pré-définie. Concrètement, il faut utiliser un éditeur de texte pour créer un fichier qui s’appelle document.xml (à titre d’exemple, car le nom peut être quelconque).

vi document.xml

Ensuite saisir le contenu:

<?xml version="1.0" encoding="UTF-8"?>
<book xml:id="doc" xmlns="http://docbook.org/ns/docbook" version="5.0" lang="fr">
</book>

Ceci crée un document conforme aux spécifications DocBook mais vide. On reconnait en première ligne l’en-tête d’un fichier XML qui indique la version XML utilisée et l’encodage du texte (UTF-8, recommandé). La 2eme et la 3eme lignes constituent respectivement les balises de début et de fin du document. La 2eme ligne contient les paramètres principaux du document créée:

xml:id : Identifiant unique du document
xmlns : l’url du namespace DocBook, utiliser toujours http://docbook.org/ns/docbook
version: Version de DocBook utilisée, actuellement 5.0 est la version stable.
lang: Code ISO de la langue du document.

Enregistrer le fichier puis exécuter:

xsltproc -o document.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl document.xml

Il s’agit d’un appel au processeur xslt, xsltproc, avec trois paramètres:

-o : Indique le nom, au choix du document à générer.
2ème paramètre: Chemin et nom du fichier xsl du format cible, ici le format html.
3ème paramètre: le fichier du contenu à transformer.

Cette commande doit réussir et générer le fichier document.html dont le contenu est vide. Pour le vérifier, ouvrez ce fichier dans un navigateur web.

Ajouter un contenu au document.

Modifier le fichier document.xml de manière à ajouter un titre, un chapitre à un seul paragraphe:

<?xml version="1.0" encoding="UTF-8"?>
<book xml:id="doc" xmlns="http://docbook.org/ns/docbook" version="5.0" lang="fr">
  <title>Utiliser DocBook pour créer un document multi-usages</title>
  <chapter xml:id="ch1">
    <title>Introduction</title>
    <section xml:id="ch1se1">
      <title>Qu'est ce que DocBook ?</title>
      <para>
        Un ensemble d'outils XML.
      </para>
    </section>
  </chapter>
</book>

Maintenant la même commande permet d’obtenir un résultat plus significatif dans document.html:

Les éléments ajoutés au document sont dans l’ordre: . Titre du document (<title>xxxx</title>) . Un chapitre (<chapter>xxxx</chapter>) . Au sein du chapitre:

. Titre du chapitre (<title>xxxx</title>) . Une section qui génère un numéro de paragraphe

. Au sein de la section: . Titre de la section (<title>xxxx</title>) . Un paragraphe, non numéroté (<para>xxxx</para>)

Générer le document au format PDF

Deux commandes successives doivent être exécutées:

xsltproc -o document.fo /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl document.xml
fop -pdf document.pdf -fo document.fo

La première commande est similaire à celle utilisée pour générer le format html. La seule différence est l’utilisation d’un autre fichier xsl: /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl au lieu de /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl Cette première commande génère un fichier intermédiaire, document.fo, qui sera utilisé par la deuxième commande qui génère le fichier document.pdf]]>