DocBook - Wikiwand

Remove ads

DocBook est un langage de balisage sémantique pour la documentation technique. À l'origine 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.

Remove ads

Avantages

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 (Boeing, HewLett-Packard, ...).

Remove ads

Histoire

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

Remove ads

Porteurs du projet

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]) :

Davantage d’informations Personne, Organisation ...

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

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.

Remove ads

Créer un document DocBook

Résumé

Contexte

Outils pour DocBook SGML

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

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.

Remove ads

Organisation d'un document DocBook

Résumé

Contexte

Exemples de codes

Exemple pour un livre en DocBook version 4.5 (modèle de livre géré par Publican).

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "DocBook_Template.ent">
%BOOK_ENTITIES;
]>
<book>
	<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<index />
</book>

Avec comme fichier Book_Info.xml :

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "DocBook_Template.ent">
%BOOK_ENTITIES;
]>
<bookinfo id="book-Modele_de_livre_DocBook-DocBook_Template-DocBook_Template">
	<title>DocBook Template</title>
	<subtitle>Entrez ici une courte description.</subtitle>
	<productname>Modele de livre DocBook</productname>
	<productnumber>0.1</productnumber>
	<edition>0</edition>
	<pubsnumber>0</pubsnumber>
	<abstract>
		<para>
			Un court aperçu, un résumé du propos de l'ouvrage et ses objectifs, ne dépassant pas en général un paragraphe. Note : le résumé est affiché dans les pages liminaires de l'ouvrage et est également placé dans le champ « description » du fichier spec du RPM de l'ouvrage.
		</para>
	</abstract>
	<corpauthor>
		<inlinemediaobject>
			<imageobject>
				<imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
			</imageobject>
		</inlinemediaobject>
	</corpauthor>
	<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>

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

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.

Remove ads

Notes et références

Loading content...

Voir aussi

Loading content...

Loading related searches...

Wikiwand - on

Seamless Wikipedia browsing. On steroids.

Remove ads