G.4. Écriture de la documentation

PSGML™ est le mode d'édition de documents SGML le plus répandu et le plus puissant. S'il est correctement configuré, il permet d'utiliser Emacs pour insérer des balises et en vérifier la cohérence. Il peut aussi être utilisé pour le HTML. Visiter 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.

L'auteur de PSGML™ suppose que le répertoire principal pour la DTD SGML est /usr/local/lib/sgml. Si, comme c'est le cas dans les exemples de ce chapitre, le répertoire /usr/local/share/sgmlest utilisé, il faut modifier la variable d'environnement SGML_CATALOG_FILES ou personnaliser l'installation de PSGML™ (son manuel indique la procédure).

Ajouter les lignes suivantes dans le fichier d'environnement ~/.emacs (en ajustant les noms des répertoires pour qu'il convienne au 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 ajouter l'entrée pour le SGML dans la définition (existante) pour auto-mode-alist :

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

La distribution PostgreSQL™ inclut un fichier DTD pré-traité contenant des définitions appelé reference.ced. Il peut s'évérer plus confortable pour gérer des fichiers séparés d'insérer une déclaration DOCTYPE propre lors de l'édition d'un fichier avec PSGML™. Si l'on considère le fichier source de cette annexe, par exemple, il est possible de préciser 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 fait correctement et que la validité du document peut être vérifiée avec nsgmls -s docguide.xml . (Cependant, il faut supprimer la ligne avant de fabriquer le document complet à partir des différents fichiers.)

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 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.