DocBook
Cet article est une ébauche concernant l’informatique.
Vous pouvez partager vos connaissances en l’améliorant (comment ?) selon les recommandations des projets correspondants.
Cet article ne cite pas suffisamment ses sources ().
Si vous disposez d'ouvrages ou d'articles de référence ou si vous connaissez des sites web de qualité traitant du thème abordé ici, merci de compléter l'article en donnant les références utiles à sa vérifiabilité et en les liant à la section « Notes et références ».
En pratique : Quelles sources sont attendues ? Comment ajouter mes sources ?
DocBook est un langage de balisage sémantique pour la documentation technique. À l'origene prévu pour écrire de la documentation technique portée sur le domaine informatique (matériel et logiciel), il peut être utilisé pour n'importe quel type de documentation.
En tant que langage sémantique, DocBook permet à ses utilisateurs de créer du contenu sous une forme neutre vis-à-vis de la présentation qui ne fait que capturer la structure logique du contenu; contenu qui peut ensuite être publié dans une grande variété de formats, notamment HTML, XHTML, EPUB, PDF, pages de man, Web help et HTML Help, sans obliger les utilisateurs à faire des changements dans le contenu source. En d'autres termes, quand un document est écrit dans le format DocBook il devient facilement portable vers d'autres formats. Il résout ainsi le problème de reformatage en n'ayant à écrire qu'une seule fois à base de balises XML.
Avantages
[modifier | modifier le code]Le format DocBook ne contient que des données et aucune information de mise en forme, c'est pourquoi DocBook est lisible sans aucun outil spécifique en plus d'être facile à exploiter. De plus, de très nombreux outils savent exploiter le format DocBook (LibreOffice/OpenOffice, XML Copy Editor, etc.)
Le format DocBook est adapté aux traitements par lots, il est donc un format idéal pour l'archivage.
Pour toutes ces raisons, DocBook s'est imposé comme le format standard pour la documentation logicielle (notamment dans la communauté Open Source) et commence à être utilisé dans l'industrie.[réf. nécessaire]
Histoire
[modifier | modifier le code]DocBook a été conçu par HAL Computer Systems (en) et O'Reilly & Associates en 1991 en s'inspirant des travaux de l'Open Software Foundation qui envisageait le langage SGML pour écrire les manuels de référence des versions OSF d'UNIX.
La popularité croissante du projet engendra la création du Davenport Group qui est officiellement chargé du projet dès 1994.
Depuis 1998, DocBook est géré par le DocBook Technical Commitee de l'organisme de normalisation OASIS. De ce fait, il est indépendant vis-à-vis des logiciels propriétaires.
À l'origene le schéma DocBook est une DTD SGML qui deviendra également un schéma XML à partir de la version 4.1. Maintenant (v5.x), DocBook est également une grammaire XML définie par les schémas RelaxNG, W3C XML Schema[1].
La Version 5.1 de DocBook apporte de nouvelles fonctionnalités pour réaliser de la documentation modulaire de manière beaucoup plus évoluée.
Porteurs du projet
[modifier | modifier le code]Depuis 1998, DocBook est maintenu par le DocBook Technical Committee d'OASIS. Il s'agit d'un groupe de personnes chargé du développement et de l'évolution du standard DocBook. Actuellement, les membres visibles publiquement sont (le tableau ci-dessous est directement issu du site d'OASIS[2]) :
| Personne | Organisation | Rôle |
|---|---|---|
| Larry Rowland | Hewlett-Packard | Membre votant |
| Richard Hamilton | Individu | Secrétaire |
| Nancy Harrison | Individu | Membre |
| Jirka Kosek | LexisNexis, a Division of Reed Elsevier | Membre votant |
| Robert Stayton | Individu | Président |
| Norman Walsh | Mark Logic Corporation | Membre votant |
| Patricia Gee | Oracle | Membre |
| Scott Hudson | The Boeing Company | Membre votant |
DocBook étant un standard, il est porté par une large communauté constituée à la fois de groupes/entreprises et d'individus[3]. Environ 100 acteurs principaux portent le standard, l'utilisent ou contribuent à son développement. Le langage est notamment porté par la communauté de l'open source qui s'en sert pour les documentations techniques de nombreux projets. Par exemple, les documentations des projets GNOME, KDE, FreeBSD, OpenACS,... sont écrites en DocBook.
Un format séparant le contenu de la présentation
[modifier | modifier le code]DocBook est un schéma, son rôle est de définir la structure logique, c'est-à-dire l'organisation des éléments d'un document. Contrairement à des formats de traitement de texte, tel l'OpenDocument, le format DocBook ne contient strictement que le contenu du document, présenté de façon hiérarchisée.
DocBook n'est pas directement un format de document fini mais a plutôt pour but de produire des documents dans les formats souhaités.
L'organisation physique et spatiale d'un document n'est pas gérée par DocBook. Il n'est ainsi pas possible de spécifier en DocBook des couleurs de texte ou de mise en forme. C'est le rôle de feuilles de style de gérer la présentation du document. Il existe des feuilles de style par exemple pour générer, à partir du document DocBook, du PDF ou du HTML.
Ces feuilles de style peuvent se paramétrer pour adapter l'apparence du résultat à telle ou telle charte graphique. Elles sont en général écrites en langage XSLT, sans que ce soit une obligation.
Créer un document DocBook
[modifier | modifier le code]Outils pour DocBook SGML
[modifier | modifier le code]Auparavant, lorsque DocBook était un langage SGML, un fichier DocBook était converti dans un autre format grâce à une feuille de style DSSSL spécifiant comment transformer le fichier en un document au format lisible (PDF par exemple).
À l'époque de DocBook SGML, on utilisait les DocBook-tools, un groupe de packages gratuits, fonctionnant ensemble et permettant entre autres de former des documents finis à partir de fichiers DocBook.
Parmi les formats de publication (formats finaux, simplement lisibles par l'œil humain), les fichiers DocBook peuvent être convertis notamment en HTML, DVI (TeX), PDF, PostScript, RTF,...
Pour la création de documents DocBook, il était nécessaire d'avoir :
- le package sgml-common qui contient les outils et les ressources de base nécessaires à la production de document SGML (il sert à créer et à maintenir des catalogues SGML centralisés),
- le logiciel jade qui transforme les fichiers DocBook en formats de publication à partir des DTD et des DSSSL.
- le package jadetex qui contient les macros permettant de générer un fichier TeX intermédiaire qui sera transformé ensuite en un fichier final formaté.
- la DTD DocBook : docbook-dtdXX-sgml, qui contient la version XX de la DTD de DocBook,
- et docbook-style-dsssl où se trouve, comme son nom d'indique, les feuilles de styles DSSSL.
Étaient également nécessaires les packages perl-SGMLSpm et docbook-utils. Le premier est l'interface entre Perl et SGML. Le deuxième contient un ensemble des scripts simplifiant la manipulation de jade.
Outils pour DocBook XML
[modifier | modifier le code]Aujourd'hui, DocBook respecte le standard XML, sa conversion vers un autre format se fait par l'intermédiaire de feuilles de style XSL, une conversion est réalisée vers XSL-FO dont le processeur va ensuite pouvoir convertir le fichier vers un format final.
Les documents finaux peuvent être au format HTML, PDF, PCL, PS, SVG…
Les packages à installer sont différents et moins nombreux que pour DocBook SGML :
- docbook-dtdXX-xml qui contient le schéma DTD de la version XX de DocBook ;
- docbook-style-xsl, où se trouvent les feuilles de styles XSL ;
- libxslt (qui a besoin de la bibliothèque XML libxml2), le moteur de transformation XSLT qui permet le passage vers un document lisible.
Un environnement Java est nécessaire pour FOP (Formatting Objects Processor), le processeur XSL-FO.
Organisation d'un document DocBook
[modifier | modifier le code]Exemples de codes
[modifier | modifier le code]Exemple pour un article en Docbook version 4
<book id="exemple_de_livre">
<title>Livre très simple</title>
<chapter id="exemple_de_chapitre">
<title>Chapitre très court</title>
<para>Bonjour tout le monde !</para>
<para>Ceci est un autre paragraphe...</para>
</chapter>
</book>
Exemple pour un article en Docbook version 5
<?xml version="1.0" encoding="ISO-8859-15"?>
<article version="5.0" xml:lang="fr" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook">
<info>
<title>Titre de l'article</title>
<author>
<personname><surname>Moi Même</surname></personname>
</author>
<pubdate>2011</pubdate>
</info>
<section xml:id="first_section"><title>Titre de la section</title>
<para>Bonjour tout le monde !</para>
<para>Autre paragraphe...</para>
</section>
</article>
Organisation générale
[modifier | modifier le code]Pour tout fichier DocBook, la structure générale du document est sensiblement la même.
L'élément racine, la balise <article> ou <book> englobe la totalité des éléments du document.
DocBook définit un livre comme étant un ensemble composé d'un bloc où sont inscrits les méta informations concernant celui-ci(<bookinfo>), d'une suite de chapitres (<chapter>), éventuellement d'une suite d'annexes(<appendix>) et/ou d'un glossaire.
Le bloc <bookinfo> contient des informations telles que le nom de (ou des) auteur(s), le titre du livre, ou encore la date de sa publication. Un chapitre est une suite de sections (<sect1>), elles-mêmes pouvant être divisées en un certain nombre de sous-sections, et ce récursivement (<sect2>,...).
Les chapitres et les sections comportent tous un titre (<title>) et au moins un paragraphe (<para>). À l'intérieur de ces paragraphes, on peut trouver du texte, des images, des listes, des tableaux,...
Les annexes ont la même structure que les chapitres.
Pour les articles, la structure est allégée, on retrouve le bloc méta-information (<info>) mais les balises <chapter> n'existent plus, on passe directement aux niveaux de sections (<sect1>, <sect2>,...). De même, il n'y a plus d'annexes, ni de glossaire.
Notes et références
[modifier | modifier le code]- « What is DocBook? », sur docbook.org (consulté le ).
- (en) « OASIS DocBook TC Technical Committee », sur oasis-open.org (consulté le ).
- (en) « WhoUsesDocBook », sur GitHub (consulté le ).
Voir aussi
[modifier | modifier le code]Articles connexes
[modifier | modifier le code]Liens externes
[modifier | modifier le code]- (en) Site officiel de documentation
- (en) DocBook Wiki
- (en) Page d'accueil du projet sur sourceforge (dépôt des fichiers)
- (en) Site relatif à la normalisation de DocBook
- (en) FOP, le moteur XSL-FO d'Apache
