4. Démarrer avec DocBook

4.1.1. Méthode manuelle pour Jade/OpenJade

Ceci est la méthode rapide mais pas très propre ("quick and dirty") qui devrait marcher pour toutes les distributions.

1. Créer un répertoire de base où installer tous les outils, par exemple /usr/local/sgml/. Dans la suite nous l'appellerons $_toolroot.

2. Installer Jade, la DTD DocBook et DSSSL dans le répertoire $_toolroot (en y créant les sous-répertoires $_toolroot/jade-1.2.1, $_toolroot/dtd, $_toolroot/dsssl).

3. Vous aurez besoin de définir la variable d'environnement SGML_CATALOG_FILES pour indiquer les catalogues dont vous disposez dans $_toolroot. Vous pouvez le faire avec la commande bash$ export SGML_CATALOG_FILES = $_toolroot/dtd/docbook.cat:$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog

4. Maintenant vous pouvez utiliser Jade. Pour créer des fichiers HTML séparés :

   $_toolroot/jade-1.2.1/jade/jade -t sgml -i html -d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml

5. Pour créer un unique document HTML, ajoutez -V nochunks à la liste des paramètres passés à Jade.

4.1.2. sgmltools

Contrairement à LinuxDoc, vous aurez besoin d'une version 2.x de sgmltools pour utiliser DocBook. Puisque la plupart des distributions ne contiennent qu'une version 1.x, vous devrez supprimer le paquetage sgmltools 1.x et installer une version 2.x ou une version CVS. Pour récupérer les sources de la dernière version CVS vous pouvez utiliser les commandes suivantes :

bash$ CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs 
bash$ export CVSROOT 
bash$ cvs login 
bash$ cvs -z6 get sgmltools

Le mot de passe CVS est 'cvs'. Une fois le téléchargement terminé, vous pouvez utiliser

bash$ ./compile 
bash$ make 
bash# make install

pour installer sgmltools. Pour les systèmes RedHat (utilisant RPM) vous pouvez utiliser la commande rpmfind pour récupérer la dernière version. Le programme rpmfind est disponible à l'adresse http://www.rpmfind.net/. Vérifiez que vous récupérez bien sgmltools et non sgml-tools, car ce dernier paquetage est en fait une version 1.0.9 qui ne marche que pour les documents utilisant LinuxDoc. Pour les systèmes Debian, version 2.2 "Potato" ou plus, apt-get récupérera le bon paquetage pour vous :

bash# apt-get install sgmltools-2

Comme pour les systèmes RedHat, le paquetage sgml-tools est obsolète. Assurez-vous de récupérer sgmltools-2.

4.1.3. Les outils DocBook de Cygnus

Ces outils sont fournis avec la Red Hat 6.2. Vérifiez que les paquetages suivants sont installés :

• sgml-common

• docbook

• stylesheets

Vous trouverez la dernière version sur le site de Red Hat : http://www.redhat.com/support/errata/RHBA-2000022-01.html.

Téléchargez/récupérez les fichiers RPM sur votre machine et installez-les de la manière habituelle (en tant que super-utilisateur : rpm -Uvh nomdufichier). Une fois les RPMs installés, vous pouvez utiliser les commandes suivantes pour convertir les fichiers DocBook :

bash$ db2html nomdufichier

pour convertir du DocBook en HTML. Un sous-répertoire de même nom que le fichier (sans l'extension .sgml) est créé et les fichiers HTML y sont placés.

bash$ db2pdf nomdufichier

pour convertir un fichier DocBook en un fichier PDF.

4.3.1. Nouveaux documents

Vous pouvez facilement commencer un nouvel HOWTO en utilisant LyX. La commande de menu Fichier->Nouveau depuis modèle... vous permet de choisir un modèle de document. Cliquez sur Modèles sur la droite de la boîte de dialogue puis sélectionnez docbook_template.lyx dans la liste des fichiers. Cliquez sur OK et vous aurez alors un document vierge. Remplissez les champs proposés tels que le titre, le résumé, le nom de l'auteur, puis commencez la rédaction.

4.3.2. Documents existants

Si vous disposez d'un document LyX, TeX ou texte, vous pouvez l'importer dans LyX grâce à la commande Fichier->importer. Une fois le fichier importé, utilisez la commande Mise en Page->Document... Choisissez l'entrée SGML (DocBook Article) dans le menu Type. Il vous sera demandé si vous voulez convertir tout le texte ; dites Oui. Vous devrez réappliquer les balises, mais cela consiste juste à sélectionner du texte et à choisir un style. La plupart des fonctions LyX disposent d'un raccourci clavier.

4.3.3. Exporter vers SGML

Pour commencer, sauvegardez votre document au format LyX. Cela vous permettra d'éditer les futures versions plus facilement. Utilisez ensuite la commande Fichier->Exporter->DocBook... pour exporter votre fichier au format DocBook.

4.4.1. Introduction

Si vous disposez d'une distribution récente, PSGML est certainement déjà installé avec Emacs. Pour vérifier, lancez Emacs et cherchez la documentation sur PSGML (C-h i m psgml).

A partir de maintenant nous supposerons que PSGML est installé correctement au sein d'une version récente de GNU Emacs. Si tout cela va trop vite pour vous, consultez le chapitre librement disponible du livre de Bob Ducharme : http://www.snee.com/bob/sgmlfree/.

4.4.2. Mise à jour du fichier .emacs pour PSGML

Si vous voulez que GNU Emacs utilise automatiquement le mode PSGML quand vous ouvrez un fichier .sgml, vérifier que PSGML saura où trouver la DTD DocBook. Si PSGML était déjà installé sur votre système, vous n'aurez certainement rien à faire. Sinon, vous devrez définir une variable d'environnement qui indiquera où trouver le catalogue SGML (la liste des DTD).

Par exemple :

bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog

Ensuite ajouter les lignes suivantes à votre fichier .emacs 

;; *******************************************************************
;; set up psgml mode...  
;; use psgml-mode instead of emacs native sgml-mode ;;

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
(setq auto-mode-alist (append (list '("\\.sgm$" . sgml-mode)
'("\\.sgml$" . sgml-mode) ) auto-mode-alist))

;; set some psgml variables

(setq sgml-auto-activate-dtd t) (setq sgml-omittag-transparent t)
(setq sgml-balanced-tag-edit t) (setq
sgml-auto-insert-required-elements t) (setq
sgml-live-element-indicator t) (setq sgml-indent-step nil)

;; create faces to assign to markup categories

(make-face 'sgml-comment-face) (make-face 'sgml-start-tag-face)
(make-face 'sgml-end-tag-face) (make-face 'sgml-entity-face)
(make-face 'sgml-doctype-face) ; DOCTYPE data 
(make-face 'sgml-ignored-face) ; data ignored by PSGML
(make-face 'sgml-ms-start-face) ; marked sections start 
(make-face 'sgml-ms-end-face) ; end of marked section 
(make-face 'sgml-pi-face) ; processing instructions 
(make-face 'sgml-sgml-face) ; the SGML declaration
(make-face 'sgml-shortref-face) ; short references

;; view a list of available colors with the emacs-lisp command: ;; ;;
list-colors-display ;; ;; please assign your own groovy colors,
;; because these are pretty bad
(set-face-foreground 'sgml-comment-face "coral"
;(set-face-background 'sgml-comment-face "cornflowerblue")
(set-face-foreground 'sgml-start-tag-face "slateblue")
;(set-face-background 'sgml-start-tag-face "cornflowerblue")
(set-face-foreground 'sgml-end-tag-face "slateblue")
;(set-face-background 'sgml-end-tag-face "cornflowerblue")
(set-face-foreground 'sgml-entity-face "lavender")
;(set-face-background 'sgml-entity-face "cornflowerblue")
(set-face-foreground 'sgml-doctype-face "lavender")
;(set-face-background 'sgml-doctype-face "cornflowerblue")
(set-face-foreground 'sgml-ignored-face "cornflowerblue")
;(set-face-background 'sgml-ignored-face "cornflowerblue")
(set-face-foreground 'sgml-ms-start-face "coral")
;(set-face-background 'sgml-ms-start-face "cornflowerblue")
(set-face-foreground 'sgml-ms-end-face "coral")
;(set-face-background 'sgml-ms-end-face "cornflowerblue")
(set-face-foreground 'sgml-pi-face "coral")
;(set-face-background 'sgml-pi-face "cornflowerblue")
(set-face-foreground 'sgml-sgml-face "coral")
;(set-face-background 'sgml-sgml-face "cornflowerblue")
(set-face-foreground 'sgml-shortref-face "coral")
;(set-face-background 'sgml-shortref-face "cornflowerblue")

;; assign faces to markup categories

(setq sgml-markup-faces ' ( (comment . sgml-comment-face) (start-tag
  . sgml-start-tag-face) (end-tag . sgml-end-tag-face) (entity
  . sgml-entity-face) (doctype . sgml-doctype-face) (ignored
  . sgml-ignored-face) (ms-start . sgml-ms-start-face) (ms-end
  . sgml-ms-end-face) (pi . sgml-pi-face) (sgml . sgml-sgml-face)
  (shortref . sgml-shortref-face) ))

;; tell PSGML to pay attention to face settings ;;
(setq sgml-set-face t)
;; ...done setting up psgml-mode.  ;;
*******************************************************************

Puis relancer Emacs.

4.4.3. SGML "Smoke Test"

Essayez le test suivant. Créez un nouveau document, /tmp/test.sgml par exemple, et insérez le texte suivant :

<!DOCTYPE test [ <!ELEMENT test - - (#PCDATA)> ]>

Tapez C-c C-p. Si Emacs parvient à accéder à votre DTD, vous verrez le message Parsing prolog...done dans le minibuffer. Essayez ensuite C-c C-e ENTREE pour insérer un élément <test>. Si tout s'est bien passé, vous devriez voir ceci :

<!DOCTYPE test [ <!ELEMENT test - - (#PCDATA)> ]>
<test></test>

4.4.4. Ecrire un nouveau HOWTO avec DocBook

Démarrez un nouveau fichier pour le HOWTO avec le texte suivant :

<!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

Tapez C-cC-p et retenez votre souffle. Si tout se passe comme prévu, Emacs va tourner pendant quelques secondes puis afficher le message Parsing prolog...done dans le minibuffer.

A partir de là, utilisez C-cC-eRETURN pour insérer une balise <article> et commencer à taper votre texte.

4.4.5. Référence non-exhaustive sur PSGML pour Emacs

Voir le document d'introduction de Nik Clayton, dans la documentation FreeBSD : http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html