Exposé système - DocBook

Table des matières

Historique
Les technologies
XSLT
XSL-FO
XPath
MathML
DocBook
DocBook : strucurée
DocBook : multi supports
Modulaire
Rappel des bénéfices
Rappel des difficultés
Step in
Elements de hiérarchie
Elements d'information
Exemples
Outils d'édition
XMLmind XML Editor
Conclusion
Ressources
Téléchargements
Liens

Résumé

Ce site fait suite à un exposé de système dans le cadre de la filière Informatique et Réseau de l'école Ingénieurs 2000 au sein de l'université de Marne-la-Vallée. Ce site vous est offert par Cédric Pronzato (l'auteur) et Mr Dominique Revuz (l'enseignant de système et dépositaire des ressources de cet exposé).

DocBook est un format consue pour l'édition de documentation, il est même spécialisé dans la documentation technique informatique. Le principe de base étant la séparation du fond et de la forme. Ce document présentera DocBook dans sa version 4 de manière généraliste plutôt que les aspects techniques de l'utilisation de DocBook (installation, écriture de feuille XSLT, ...) qui prendraient beacoup trop de temps, néanmoins nous donnerons quelques exemples lorsque nécessaire.

Historique

DocBook est agé d'environ une quinzaine d'année avec la version 1.0 datant de novembre 1992 dans le cadre d'un projet d'échange de documentation Unix chez O'Reilli.

Il est ensuite observer par des grands de l'informatique tels que Novel, Sun, Digital, IBM qui l'adopent comme format pour leurs documentations.

L'année 1999 marque le passage de DocBook dans un un consortium modial à but non lucratif nommé OASIS (Organization for the Advancement of Structured Information Standards). Ce dernier gère aussi la normalisation d'OpenDocument utilisé par OpenOffice.

DocBook est toujours en développement, ce qui assure ca mise à jour et son adaptation. La version stable courante est la v4, celle en cour de développement est la v5.

Les technologies

Les technologies mises en jeu dans DocBook sont l'XML et ses dialectes telles que XSLT, XSL-FO, SVG, ... On peut préciser que tous ces langages sont des standards libres.

Les langages à base d'XML sont robustes, ce qui facilite l'interopérabilité et la communication, et sont manipulables aussi bien par des humains que par des machines. C'est cette dernière capacité qui rend XML si attractif.

La robustesse est principalement dûe au format text d'XML et au processus de validation qui permet de vérifier qu'un document XML est conforme à sa grammaire, qui est généralement sous la forme d'une DTD. Si le document XML est valide par rapport à sa DTD, il est dit cohérent.

Sous linux, on peut utiliser la commande suivante pour effectuer la validation (la pluspart des éditeurs XML procèdent directement la validation) :

xmllint -valid mydocument.xml

Nous serons donc amenés à utiliser :

  • XML (eXtensible Markup Language) : Langage de balisage.

  • XSL (eXtensible Stylesheet Language) : Langage de description de feuilles de style associé à XML.

XSLT

Pour XSL Transform, langage pour transformer l'XML. Il est généralement utilisé pour transformer l'XML vers un autre format de type texte mais il peut aussi être utilisé pour générer des fichiers binaires.

En effet, on utilise très peu XML pour faire de l'affichage, ... mais on utilise une feuille de transformation XSLT afin de transformer un document XML source en un autre document permettant l'affichage, l'impression, ...

On prendra le document XML suivant comme source :

<catalog>
  <cd>
    <title>Empire Burlesque</title>
    <artist>Bob Dylan</artist>
    <country>USA</country>
    <company>Columbia</company>
    <price>10.90</price>
    <year>1985</year>
  </cd>
</catalog>

et utiliser la feuille XSLT suivante pour transformer la source en HTML :

Exemple 1. Exemple XSLT

<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:template match="/">
  <html>
  <body>
    <h2>My CD Collection</h2>
    <table border="1">
    <tr bgcolor="#9acd32">
      <th align="left">Title</th>
      <th align="left">Artist</th>
    </tr>
    <xsl:for-each select="catalog/cd">
    <tr>
      <td><xsl:value-of select="title"/></td>
      <td><xsl:value-of select="artist"/></td>
    </tr>
    </xsl:for-each>
    </table>
  </body>
  </html>
</xsl:template>

</xsl:stylesheet>

Sous linux, on peut utiliser la commande suivante pour réaliser une transformation :

xsltproc stylesheet.xsl mydocument.xml

XSL-FO

Pour XSL Formattion Objects, vocabulaire XML de mise en forme indépendant du support : papier, écran, ...

Ce vocabulaire est assez complexe car très pointu pour effectuer de publication de bonne facture.

Voici un exemple présentant la structure de base d'un document XSL-FO :

Exemple 2. Exemple XSL-FO

<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">

<fo:layout-master-set>
  <fo:simple-page-master master-name="A4">
    <!-- Page template goes here -->
  </fo:simple-page-master>
</fo:layout-master-set>

<fo:page-sequence master-reference="A4">
  <!-- Page content goes here -->
</fo:page-sequence>

</fo:root>

XPath

Pour XML Path Language, langage d'expression utilisé par XSLT pour travailler sur les arbres XML.

On prendra le document xml suivant comme source :

<article>
  <title>Titre</title>
  <para id="terminator"></para>
</article>

et les expressions XPath suivantes :

Expression XPathRésultat
/Récupère tout le document
/articleRécupère l'élément article
//paraRécupère tous les éléments para
//para[@id="terminator"]Récupère sulement les éléments para dont l'id est terminator.

MathML

Pour Math Modeling Language, vocabulaire XML permettant l'expression de symboles mathématiques.

Standard destiné à l'affichage d'expressions mathématiques sur le web.

Exemple 3. Formule mathématique

s'écrit de la manière suivante en Tex :

Exemple 4. Formule mathématique en Tex

x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

s'écrit de la manière suivante en MathML :

Exemple 5. Formule mathématique en MathML

<math>
 <mrow> 1
  <mi>x</mi> 2
  <mo>=</mo> 3
  <mfrac>
    <mrow>
      <mrow>
        <mo>-</mo>
        <mi>b</mi>
      </mrow>
      <mo>&PlusMinus;</mo> 4
      <msqrt>
        <mrow>
          <msup>
            <mi>b</mi>
            <mn>2</mn>
          </msup>
          <mo>-</mo>
          <mrow>
            <mn>4</mn>
            <mo>&InvisibleTimes;</mo> 5
            <mi>a</mi>
            <mo>&InvisibleTimes;</mo>
            <mi>c</mi>
          </mrow>
        </mrow>
      </msqrt>
    </mrow>
    <mrow>
      <mn>2</mn>
      <mo>&InvisibleTimes;</mo>
      <mi>a</mi>
    </mrow>
  </mfrac>
 </mrow>
</math>
1

Conteneur d'expression mathématique.

2

Identifiant

3

Operateur

4

Entités pré-codées

5

Exemple d'opérateur multiplié non visible

Exemple 6. Formule mathématique : Sommes

Exemple 7. Formule mathématique en MathML : Sommes

<mrow>
  <mstyle displaystyle='true'>
    <munderover>
      <mo>sum</mo>
      <mrow>
        <mi>i</mi>
        <mo>=</mo>
        <mn>1</mn>
      </mrow>
      <mi>&infty;</mi>
    </munderover>
    <msup>
      <mi>x</mi>
      <mi>i</mi>
    </msup>
  </mstyle>
  <mo>+</mo>
  <mstyle displaystyle='false'>
    <munderover>
      <mo>sum</mo>
      <mrow>
        <mi>i</mi>
        <mo>=</mo>
        <mn>1</mn>
      </mrow>
      <mi>&infty;</mi>
    </munderover>
    <msup>
      <mi>x</mi>
      <mi>i</mi>
    </msup>
  </mstyle>
</mrow>

DocBook

DocBook est surtout utilisé pour produire de la documentation technique dans les domaines de l’informatique, des télécommunications et des technologies de l’information qu’il vise. Comme il permet de séparer le contenu du document de sa présentation et qu’il s’agit d’un format libre et largement documenté, il garantit des documents pérennes. Il est particulièrement adapté au travail partagé de plusieurs auteurs ainsi qu’aux collections importantes de documents devant être mises à jour ou réorganisées fréquemment.

DocBook : strucurée

DocBook se veut être un format permettant la rédaction de documents de manière structurée.

Par structuré on entend que chaque élément est très clairement identifié :

  • par leur nom de balise

  • par leur attributs

  • par leur relation avec les autres éléments

Cette structuration permet d'avoir un format robuste, claire et introduit de la valeur ajoutée grace à toutes les meta-données qu'on peut introduire. Mais elle a aussi un coût, DocBook comporte plus de 400 éléments XML différents.

DocBook : multi supports

DocBook autorise en gain de productivité car la rédaction n'est faite qu'une seule fois et indépendament des supports cibles car les parties contenu et présentation sont séparées.

Ce document étant lui même réalisé en DocBook, il sera donc disponible sous plusieurs formats mais la rédaction à été unique.

La distribution de base fournit les transformations pour les supports suivants : PDF (via xsl-fo), PS (via xsl-fo), (X)HTML, HTML help, Java help et Eclipse help.

On peut aussi trouver d'autre transformations telles que : WordML, OpenDocument, ...

On peut noter que les fichiers sources DocBook, étant donné leur nature XML, peuvent être issue de transformations à partir de OpenOffice, Word, ...

Modulaire

La modularité de DocBook est aussi un atout très appréciable, elle se présente sous deux formes :

La premère forme de modularité se trouve au niveau des sources elles mêmes avec la possibilité de réaliser des inclusions (locales ou distantes) d'autres sources. L'inclusion peut principalement s'effectuer de deux manières différentes : XML et XInclude.

La suite d'exemples suivants présentent la manière XML :

Exemple 8. Document incluant

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY chap1 SYSTEM "Chap_Priorites_Developpement.xml">
<!ENTITY chap2 SYSTEM "use_case.xml">
<!ENTITY chap3 SYSTEM "Chap_packages.xml">
...
<book lang="fr">
  <title>Cahier Des Charges Fonctionnel</title>
    &chap1;
    &chap2;
    &chap3;
...
</book>

Exemple 9. Document inclu

<?xml version="1.0" encoding="UTF-8"?>
<chapter>
  <title>Les priorités de développement</title>
...
</chapter>

Ici, on a utilisé la fonctionnalité interne d'XML qui est la définition d'une entité système pointant sur le fichier à inclure. Ce procédé est pratique pour des exemples simples mais devient très compliqué lorsqu'il y a beaucoup d'inclusions à faire ou lorsqu'il y a des inclusions multiples.

La suite d'exemples suivants présentent la manière XInclude :

Exemple 10. Document incluant

<?xml version="1.0" encoding="UTF-8"?>
<book lang="fr" xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>Cahier Des Charges Fonctionnel</title>
...
    <xi:include href="Chapter_001_introduction_cdc.xml"/>
    <xi:include href="Chapter_002_glossaire.xml"/>
...
</book>

Exemple 11. Document inclu

<?xml version="1.0" encoding="UTF-8"?>
<chapter>
  <title>Introduction</title>
...
</chapter>

Ici, on a utilisé le programme XInclude afin de réaliser les inclusions. Il faudra donc avoir un parser XML, ou un programme, gérant XInclude. XInclude est beaucoup plus maniable car les inclusions peuvent se faire où on en a besoin et gère les chemins relatifs. Il permet aussi la selection de la partie à inclure par l'intermédiaire d'une requête XQuery (similaire au format de XPath).

La seconde forme de modularité se trouve au niveau de la grammaire. Elle peut être diminuée ou étendue pour répondre au problématiques métiers.

On prendra ici l'exemple de Slides qui est une dérivation de DocBook pour la l'écriture de présentations sous forme de diaposives. Cette dérivation rajoute principalement les éléments suivants (liste incomplète) :

...
<!ELEMENT slides (slidesinfo, speakernotes?, foil*, foilgroup*)>
<!ATTLIST slides
  %label.attrib;
  %status.attrib;
  %common.attrib;
  %role.attrib;
>
<!ELEMENT slidesinfo ((mediaobject
       | legalnotice
       | subjectset | keywordset
       | %bibliocomponent.mix;)+)>
<!ATTLIST slidesinfo
  %common.attrib;
  %role.attrib;
>
<!ELEMENT foilgroup (foilgroupinfo?, title, subtitle?, titleabbrev?,
                   (%divcomponent.mix;)*,
                   foil+)>
<!ATTLIST foilgroup
  %label.attrib;
  %status.attrib;
  %common.attrib;
  %role.attrib;
>
<!ELEMENT foilgroupinfo ((mediaobject
        | legalnotice
        | subjectset | keywordset
        | %bibliocomponent.mix;)+)>
<!ATTLIST foilgroupinfo
  %common.attrib;
  %role.attrib;
>
<!ELEMENT foil (foilinfo?, title, subtitle?, titleabbrev?,
                (%divcomponent.mix;)+)>
<!ATTLIST foil
  %label.attrib;
  %status.attrib;
  %common.attrib;
  %role.attrib;
>
<!ELEMENT foilinfo ((mediaobject
         | legalnotice
         | subjectset | keywordset
         | %bibliocomponent.mix;)+)>
<!ATTLIST foilinfo
  %common.attrib;
  %role.attrib;
>
<!ELEMENT speakernotes (%divcomponent.mix;)*>
<!ATTLIST speakernotes
  %common.attrib;
  %role.attrib;
...

On est donc façe à une augmentation de la grammaire avec l'apparition de nouveaux éléments pour l'écriture de diapositives.

La modularité permet le travaille collaboratif et simultané car chacun peut éditer une seule section et on réaliser le document final par une inclusion de toutes les sections.

Rappel des bénéfices

Au tableau des bénéfices introduits par DocBook on peut siter les suivants :

  • Le format de type texte assure la robustesse de la source.

  • Le format de type texte assure sa lecture sur n'importe quelle machine.

  • Le format de type texte autorise le travail collaboratif.

  • Le format de type xml et ses dialiectes assure son traitement sur la plus part des machines.

  • Le format de type xml permet son traitement par d'autres applications.

  • Le format de type xml permet la modularité et la résutilisation.

  • N'utilise que des standards.

  • Gain de temps avec la rédaction unique.

Séparation du travail avec les graphistes (aussi appelés programmeurs) qui ne s'attachent qu'à la présentation d'un format de sortie particulier et avec les rédacteurs qui ne s'attachent qu'au contenu et sa signification.

Rappel des difficultés

Lors de l'utilisation de DocBook, on se rend très vite compte des difficultés suivantes :

  • L'écriture de documentation sans un éditeur XML est hardue afin de respecter la DTD.

  • Il faut connaître un minimum toutes la balises afin de pouvoir les utiliser au bon endroit.

  • L'écriture ou la réutilisation de feuille de transformation n'est pas une chose si simple que ca.

  • Beaucoup de technologies à connaître si on veut être à la fois rédacteur et graphiste.

Step in

Elements de hiérarchie

Ce sont les éléments qui servent à la structuration du document. Voici les principaux éléments :

  • Set et Book

  • Part et Reference

  • Preface, Chapter, Appendix, Bibliography, Glossary, Index

  • Article

  • Section

Les trois éléments pouvant débuter une documentation au format DocBook sont Set (collection de livres), Book (livre composé de chapitres comme sous parties) et Article (article composé de sections comme sous parties).

Elements d'information

Ce sont les éléments qui servent à donner de la signification au texte. Voici les principaux éléments :

  • Lists (ordered, itemized, ...)

  • Admonitions (caution, warning, note, ...)

  • Verbatim (programlisting, screen, ...)

  • Example, figure, and table...

  • Graphics (Mediaobject) ...

  • Inlines (link, user interfaces, programming, ...)

Exemples

Voici l'exemple d'un livre DocBook vide :

Exemple 12. Livre vide

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<book>
  <title></title>
  <chapter>
    <title></title>
    <section>
      <title></title>
      <para></para>
    </section>
  </chapter>
</book>

Voici l'exemple d'une présentation Slides vide :

Exemple 13. Présentation vide

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE slides PUBLIC "-//Norman Walsh//DTD Slides XML V3.3.0//EN"
"http://docbook.sourceforge.net/release/slides/3.3.0/schema/dtd/slides.dtd">
<slides>
  <slidesinfo>
    <title></title>
  </slidesinfo>

  <foilgroup>
    <title></title>

    <foil>
      <title></title>

      <para></para>
    </foil>
  </foilgroup>
</slides>

La feuille de transformation suivante a été écrite pour le site web de ce document. Les principales modifications seront commentées :

Exemple 14. Feuille de stransformation

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:import href="docbook-xsl-1.69.1/xhtml/chunk.xsl"/>
  <xsl:param name="html.stylesheet" select="'Xpose.css'"/> 1
  <xsl:param name="admon.graphics" select="1"/>
  <xsl:param name="chunker.output.indent" select="'yes'"/>
  <xsl:param name="navig.showtitles" select="0"/>
  <xsl:param name="chunk.tocs.and.lots" select="1"/> 2

  <xsl:template name="user.header.navigation"> 3
    <xsl:variable name="codefile" select="document('siteweb/ar01-toc.html',/)"/>
    <xsl:copy-of select="$codefile/*/node()"/>
  </xsl:template>

  <xsl:template name="chunk-element-content"> 4
    <xsl:param name="prev"/>
    <xsl:param name="next"/>
    <xsl:param name="nav.context"/>
    <xsl:param name="content">
      <xsl:apply-imports/>
    </xsl:param>
    <xsl:call-template name="user.preroot"/>
    <xsl:choose>
      <xsl:when test="$nav.context = 'toc'"> 5
        <xsl:message>Processing toc</xsl:message>
        <html>
        <head>
        </head>
        <body>
          <xsl:copy-of select="$content"/>
        </body>
        </html>
      </xsl:when>
      <xsl:otherwise> 6
        <html>
        <xsl:call-template name="html.head">
          <xsl:with-param name="prev" select="$prev"/>
          <xsl:with-param name="next" select="$next"/>
        </xsl:call-template>
          
        <body>
          <xsl:call-template name="body.attributes"/>
          <xsl:call-template name="user.header.navigation"/>
          <xsl:call-template name="header.navigation">
            <xsl:with-param name="prev" select="$prev"/>
            <xsl:with-param name="next" select="$next"/>
            <xsl:with-param name="nav.context" select="$nav.context"/>
          </xsl:call-template>

          <xsl:call-template name="user.header.content"/>
          <xsl:copy-of select="$content"/>
          <xsl:call-template name="user.footer.content"/>

          <xsl:call-template name="footer.navigation">
            <xsl:with-param name="prev" select="$prev"/>
            <xsl:with-param name="next" select="$next"/>
            <xsl:with-param name="nav.context" select="$nav.context"/>
          </xsl:call-template>

          <xsl:call-template name="user.footer.navigation"/>
        </body>
        </html>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>   
</xsl:stylesheet>
1

Déclaration de la CSS à utiliser

2

Indique qu'on souhaite avoir la table des matières et les listes des figures, exemples, ... dans des fichiers séparés.

3

Ce template est appelé pour la génération de l'entête. Ici, il est utilisé pour inclure dans chanque entête le fichier de table des matières. La table des matières sera alors placée correctement par CSS.

Dans la suite de l'exemple on comprendra que les templates sont appelés dans l'ordre suivant dans le template chunk-element-content :

  1. user.header.navigation

  2. header.navigation

  3. user.header.content

  4. user.footer.content

  5. footer.navigation

  6. user.footer.navigation

4

Ce template est appelé pour la génération de chaque fichier.

5

On utilise cette condition pour ne pas inclure la table des matières dans l'entête de la table des matières elle même.

6

Sinon, le cas normal.

L'exemple suivant indique comment transformer le source de ce document en site web pour le compte rendu de cet exposé sur DocBook.

xsltproc -output siteweb/ customisation.xsl docbook.xml

L'exemple suivant permet de transformer ce document en documentation JavaHelp. On le fait juste à titre d'exemple car il faudrait renseigner les élements pour la génération de l'index afin d'avoir une JavaHelp utilisable :

xsltproc -output javahelp/ docbook-xsl-1.69.1/javahelp/javahelp.xsl docbook.xml

Outils d'édition

N'importe quel éditeur compatible XML ou même un simple éditeur de texte est suffisant.

Néanmoins, quand on a gouté à XMLmind XML Editor, on ne peut plus s'en séparer :

XMLmind XML Editor

Ce programme Java, à fortiori utilisable sur toutes les plateformes, permet d'éditer du DocBook (est plus généralement de l'XML) de manière visuelle.

Cet outil utilise lui aussi beacoup de standards, par exemple, il utilise CSS pour gérer l'affichage.

De plus, son API est disponible sous forme de JavaDoc, il est donc possible d'écrire facilement des plugins grâce aux tutoriaux présents sur le site.

Plutôt que de faire un grand discourt, il est préférable d'aller sur le site web officiel pour se rendre compte de toutes les fonctionnalités.

Conclusion

Les seuls contraintes :

Pour maitriser DocBook du début jusqu'à la fin, il faut maitriser toutes les technologies de type XML.

Pour les rédacteur, une mini formation de quelques est nécessaire.

Pour les programmeurs et graphistes, il faudra plusieurs dizaines d'heures en fonction du support cible.

Expérience personnelle : j'ai utilisé DocBook pour notre projet de génie logiciel et nous avons gagné beacoup de temps grâce au travail collaboratif et simultané. De part le fait de la séparation de la forme et du contenu, qu'une seule personne à travaillé sur la mise en forme.

Ressources

Voici les différents ressources qui sont accéssibles :

Téléchargements

Liens