Pourquoi utiliser DocBook?

DocBook est un des cinq formats dédiés à la documentation technique, aux manuels d'utilisation par exemple. C'est un schéma XML, il décrit l'information indépendamment de la présentation.

Sommaire
Docbook, format XML de document automatique
Formater automatiquement les documents

Les quatre autres formats sont:

Pourquoi utiliser DocBook?

Les formats PDF et XPS sont plutôt dédiés à l'impression, et ils peuvent être générés à partir de documents DocBook ou texinfo, on ne les utilisera pas comme fichiers sources. PDF convient moins bien pour le web, mais semble reconnu actuellement par les moteurs de recherche.

Tex, bien qu'ancien ne dispose pas d'outil simple à utiliser.
Il en est de même pour texinfo qui requiert une édition manuelle laborieuse. Texinfo peut théoriquement être converti en DocBook avec makeinfo.

On pourrait écrire un document avec Open Office, et le convertir au format HTML ou PDF. Mais l'intérêt de DocBook est la séparation des données et de la présentation, ce qui facilite la génération automatique de document, la création ou la complétion à partir d'une source de données.
On peut traiter le document dans le cadre d'utilisations différentes: pour extraire des informations, pour affichages selon des conceptions multiples.
DocBook est maintenant le format de documentation de Linux et FreeBSD.

Comment utiliser DocBook? Convertir en PDF?

Un texte peut être édité directement, ou avec un éditeur graphique (voir les ressources plus bas).
Il est possible également de produire un document DocBook à partir d'un traitement de texte comme Open Office (mais cette fonctionnalité à besoin d'être développée à ce jour).

Pour une utilisation manuelle, il vous faudra:

Il existe des feuilles de style pour produire un fichier HTML ou XSL-FO à partir du document DocBook.

Votre document peut mentionner le DTD, par exemple:
Pour Linux, localement:

<!DOCTYPE book SYSTEM "/usr/share/DocBook-4.4/DocBookx.dtd">

Pour Windows, localement: 

<!DOCTYPE book SYSTEM "file:///C:/xml/DocBook44/DocBookx.dtd">

Sur le net:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 
    "http://www.oasis-open.org/DocBook/xml/4.4/DocBookx.dtd">

Avec le logiciel FOP et la feuille de style XSL-FO, on crée un fichier PDF avec cette commande:

java org.apache.fop.apps.Fop  -xml myfile.xml  -xsl DocBook-xsl/fo/DocBook.xsl   -PDF myfile.PDF

Exemple simple 

<book id="livre1">
  <title>Livre minimal</title> 
  <chapter id="chapitre1"> 
    <title>Chapitre d'une ligne</title>
    <para>Juste une ligne de texte</para>
  </chapter>
</book>

Contenu d'un document DocBook

Un document DocBook est un document XML utilisant des balises prédéfinies. Ces balises sont définies dans un schéma ou DTD qui sert de modèle pour décrire la structure d'un document.

Exemple de document DocBook 

<?xml version="1.0"?>
<article>
  <title>Exemple DocBook</title> 
  <section> 
    <title>
       Présentation
    </title>
  <itemizedlist>
   <listitem> 
     <para>
        élément
     </para>
   </listitem>
   <listitem> 
     <para>
        élément
     </para> 
   </listitem> 
   </itemizedlist> 
    <para> 
        autre paragraphe
    </para> 
  </section> 
</article>

Balises standard

Quelques exemples de balises:

List
<orderedlist> </orderedlist>
Index
<indexentry> </indexentry>
Table
<table> </table>
Table of contents
<ToC> </ToC>
Legal
<copyright> </copyright>
Structure
<section> <sect1> </sect1> </section>
Image
<imageobject>
<imagedata fileref="image.gif" format="gif"/>
</imageobject>

Fichier DocBook

Un fichier DocBook est un fichier XML, sans extension propre au type de fichier.

Plus d'informations

Autres formats

© 2006-2021 Xul.fr