1. Introduction

1.1. A propos de ce document

La dernière version de ce mini-howto peut être trouvée sur :

http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/

Reportez-vous à la section Annexe A pour des informations sur les copyright, licence et décharge de responsabilité relatifs à ce document.

1.2. Qu'est-ce que DocBook ?

DocBook est une Définition de Type de Documents (DTD - Document Type Definition) en Langage Standard de Balisage Généralisé (SGML - Standard Generalized Markup Language), qui définit un ensemble de balises pour des documents littéraux, et qui fonctionne comme le langage HTML utilisé habituellement sur le Web.

DocBook est destiné à la rédaction de livres et d'articles. Comme tel, il fournit des balises (appelées encore marqueurs) pensées spécifiquement pour décrire des livres et des articles. Par exemple, les balises DocBook <book> et <article> sont utilisées pour créer les livres et les articles. Dans ces documents, des balises <chapter>, <sect1>, et <para> seront utilisées. Les fichiers SGML DocBook sont stockés dans des fichiers texte avec un suffixe .sgml ou .gml

Lors de son traitement, un unique fichier SGML DocBook peut produire des fichiers HTML, PDF, PS, TXT ou d'autres formats de publication papier ou électronique. Le traitement est régi par des feuilles de style (stylesheets) qui peuvent générer automatiquement une table des matières, la numérotation des pages, la numérotation des chapitres et des sections, et bien d'autres possibilités.

DocBook est destiné également à l'écriture de pages de manuel unix, en utilisant la balise <refentry>.

1.3. Aperçu rapide

Voici une description brève des paquetages que nous utiliserons dans les prochaines sections :

OpenJade. OpenJade est un processeur DSSSL (Document Style Semantics and Specification Language - Langage de spécification et Sémantique de présentation de document) pour documents SGML (Standard Generalized Markup Language - Langage Standard de Balisage Généralisé). Il transforme des fichiers source SGML DocBook en fichiers HTML, TEX, RTF, TXT et autres formats. OpenJade est l'outil essentiel pour convertir un fichier DocBook dans d'autres formats. Le format de sortie TEX est utilisé surtout comme format intermédiaire pour obtenir des fichiers DVI, PDF et PS par des macros TeX et des convertisseurs DVI.

La DTD SGML DocBook. Les fichiers DTD (Définition de Type de Document) sont des fichiers SGML qui définissent le langage DocBook. L'ensemble des balises valides et leurs règles d'utilisation y sont définis. OpenJade a besoin d'accéder aux fichiers DTD des documents qu'il doit traiter.

ISO8879 ENTITY SGML. Les entités définissent la représentation des caractères spéciaux qui n'ont pas de touche clavier associée ou qui ont une signification particulière en SGML. Des exemples connus en HTML sont "&eacute;" pour "é","&amp;" pour "&" et "&gt;" pour ">".

DSSSL DocBook. Les fichiers DSSSL (Document Style Semantics and Specification Language) pour une DTD particulière, en l'occurrence DocBook, spécifient comment convertir le document DocBook en fichiers au format HTML, RTF, TEX, etc.

SgmlTools-lite. SgmlTools est une interface pour lancer OpenJade et les macros TeX jadetex et pdfjadetex qui en font partie. La conversion d'un fichier DocBook en format PS ou PDF est un traitement en deux ou trois étapes. OpenJade crée un fichier TEX qu'utilise jadetex pour produire un DVI, et pdfjadetex pour produire un document PDF. Un fichier PS s'obtient en transformant le fichier DVI avec dvips. Les scripts SgmlTools fournissent une commande unique pour ces tâches.

HTMLdoc. HTMLdoc est un programme libre pour convertir des fichiers HTML en documents PDF ou PS.

SGMLSpm and docbook2X. Ces deux outils sont à utiliser pour générer des pages de manuel. SGMLSpm est une bibliothèque modulaire Perl5 pour traiter les résultats du travail de onsgmls, un programme inclus dans OpenJade. SGMLSpm comprend une application appelée sgmlspl permettant d'utiliser la bibliothèque SGMLSpm. Sgmlspl nécessite des fichiers de spécification, disponibles sur de nombreux sites internet, pour chaque type de document à transformer. DocBook2X est un paquetage qui fournit des fichiers de spécification pour transformer des fichiers DocBook en pages de manuel.