G.4. Écriture de la documentation

G.4.1. Emacs/PSGML

PSGML est le mode d'édition de documents SGML le plus répandu et le plus puissant. S'il est correctement configuré, il vous permettra d'utiliser Emacs pour insérer de balises et en vérifier la consistance. Vous pouvez également l'utiliser pour le HTML. Visitez le site web de PSGML pour le télécharger, avoir des informations sur l'installation et pour disposer d'une documentation détaillée.

Un point important à noter avec PSGML : son auteur suppose que votre répertoire principal pour la DTD SGML est /usr/local/lib/sgml. Si, comme c'est le cas dans les exemples de ce chapitre, vous utilisez le répertoire /usr/local/share/sgml, vous devrez modifier la variable d'environnement SGML_CATALOG_FILES ou vous pouvez personnaliser votre installation de PSGML (son manuel vous renseignant sur la manière de le faire).

Ajoutez les lignes suivantes dans votre fichier d'environnement ~/.emacs (en ajustant les noms des répertoires pour qu'il convienne à votre système de fichiers) :

; ********** pour le mode SGML (psgml)

(setq sgml-omittag t)
(setq sgml-shorttag t)
(setq sgml-minimize-attributes nil)
(setq sgml-always-quote-attributes t)
(setq sgml-indent-step 1)
(setq sgml-indent-data t)
(setq sgml-parent-document nil)
(setq sgml-default-dtd-file "./reference.ced")
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
(setq sgml-ecat-files nil)

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )

et dans le même fichier ajoutez l'entrée pour le SGML dans la définition (existante) pour auto-mode-alist :

(setq
  auto-mode-alist
  '(("\\.sgml$" . sgml-mode)
   ))

Actuellement, chaque fichier source SGML contient le bloc suivant à la fin du fichier :

<!-- Conservez ce commentaire à la fin du fichier
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->

Ce bloc vous permet de définir un certain nombre de paramètres du mode d'édition même si vous n'avez pas configuré votre fichier ~/.emacs, mais il est un peu malheureux car, si vous avez suivi les instructions d'installation ci-dessus, le chemin de catalogue ne correspond pas à l'endroit où vous l'aurez mis. Si c'est le cas, vous drevrez faire en sorte de ne pas prendre en compte les variables locales :

(setq inhibit-local-variables t)

La distribution PostgreSQL inclut un fichier DTD pré-traité contenant des définitions appelé reference.ced. Vous trouverez certainement plus confortable d'insérer une déclaration DOCTYPE lorsque vous éditerez un fichier avec PSGML. Si par exemple vous travaillez sur ce fichier source qui est un chapitre annexe, vous pourrez spécifier que le document est une instance << appendix >> d'un document DocBook en ajoutant en première ligne ceci :

<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN">

Ceci signifie que, quelque soit l'outil lisant le SGML, il le fera correctement et que je peux vérifier la validité du document avec nsgmls -s docguide.sgml. (Cependant, vous devrez supprimer la ligne avant de fabriquer le document complet à partir des différents fichiers.)

G.4.2. Autres modes pour Emacs

GNU Emacs dispose d'un mode SGML natif différent qui n'est pas aussi puissant que PSGML, mais qui a le bénéfice d'être plus simple et léger. Il offre la coloration syntaxique (en mode font lock), ce qui peut être relativement utile.

Norm Walsh propose un mode majeur spécifique à DocBook qui dispose également de la coloration syntaxique et d'un certain nombre de fonctions permettant de réduire le temps de saisie.