DocBook Install mini-HOWTO

Robert B Easter

Historique des versions
Version v1.7 2001-03-28 Revu par : rbe

DocBook-Install-mini-HOWTO est un guide pratique et détaillé pour permettre aux novices d'installer rapidement DocBook et de générer des fichiers SGML en HTML, PS et PDF sur un système GNU/Linux (mais cela peut être similaire sur d'autres systèmes). La mise en place de DocBook, qui nécessite des fichiers de plusieurs paquetages distribués séparément, peut sembler confuse aux débutants.



Introduction


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 pour des informations sur les copyright, licence et décharge de responsabilité relatifs à ce document.


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.


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.


Télécharger les paquetages

Dans cette section, nous localiserons et téléchargerons les logiciels sur Internet.


OpenJade

OpenJade est un logiciel aux sources libres (open-source), activement maintenu, basé sur le paquetage Jade de James Clark. Téléchargez la dernière version stable (1.3?) sur:

http://openjade.sourceforge.net/

OpenJade inclut également le paquetage OpenSP et les macros TeX jadetex et pdfjadetex pour convertir les fichiers en DVI et en PDF. Les programmes suivants sont installés par ce paquetage:

  • openjade

  • onsgmls

  • osgmlnorm

  • ospam

  • ospent

  • osx

Afin de pouvoir utiliser jadetex et pdfjadetex pour créer du DVI, PS et PDF, vous devez avoir une installation de TeX qui fonctionne. Si vous n'avez pas TeX, cherchez dans votre distribution Linux le paquetage à installer. Sinon, vous pouvez télécharger la distribution TeX teTeX depuis :

http://www.tug.org/tetex/


La DTD SGML DocBook

Les DTD DocBook SGML et XML sont maintenues par un comité technique à Oasis-Open.ORG. Téléchargez la dernière version (et les versions anciennes dont vous pourriez avoir besoin) de DocBook SGML sur :

http://www.oasis-open.org/docbook/sgml/index.html


ISO8879 ENTITY SGML

Les entités définissent la représentation de caractères spéciaux ou de symboles qui ne peuvent être saisis au clavier, y compris les symboles mathématiques et les entités qui peuvent vous être familières avec le HTML. Ces fichiers d'entités doivent être installés pour avoir une configuration correcte.

ISOEnts.zip n'a besoin que d'être décompacté dans le répertoire de la DTD DocBook et de rien d'autre, mais les fichiers dans isoENT-tar.gz restent nécessaires. Les fichiers de isoENT-tar.gz doivent donc également être décompactés dans le répertoire de la DTD DocBook (cf. pour les détails). Mais ces fichiers possèdent un suffixe ".ent" qui doit être renommé en ".gml". Vous pouvez le faire manuellement, ou bien vous pouvez télécharger et utiliser le fichier ci-dessous, préparé par l'auteur, qui contient les fichiers des deux archives ISOEnts.zip et isoENT-tar.gz :

http://www.comptechnews.com/~reaster/iso8879-entities.tar.gz


DSSSL DocBook

Des fichiers DSSSL (Document Style Semantics and Specification Language) pour la DTD DocBook (SGML/XML) sont fournis par Norman Walsh. Ces fichiers, appelés Modular DocBook Stylesheets (feuilles de style modulaires pour DocBook), disent à OpenJade comment convertir votre fichier SGML DocBook en un autre format. Un fichier dsl décrit par exemple la correspondance entre une balise d'une DTD et une autre balise d'une autre DTD, ou d'autres conversions programmées, écrites dans un langage appelé Core Expression Language, qui est dérivé du Scheme. Le paquetage DSSSL DocBook et sa documentation peuvent être téléchargés sur le site de Norman Walsh:

http://nwalsh.com/docbook/dsssl/