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