# 9.3. Écrire de la Documentation SGML

Cette section a été ajoutée car SGML (ou pour être plus précis : la DTD LinuxDoc) semble rester difficile pour les débutants qui souhaitent écrire de la documentation. En parcourant des applications KDE, j'ai remarqué que certaines contenaient le fichier sgml de modèle mais l'auteur a ensuite édité la sortie html au lieu du fichier sgml. Il en résulte des problèmes pour les traducteurs - s'ils veulent fournir dans leur langue natale de la documentation sur votre application, ils devront éditer chaque fichier HTML et cela rend impossible la réutilisation de la documentation pour d'autres formats, pas seulement dans la version anglaise mais aussi pour toutes les versions internationalisées. Vous voyez donc que c'est un comportement limitant et une mauvaise situation ; personnellement, je pense que cela vient du fait que les auteurs connaissent HTML et non SGML. Comme beaucoup veulent éviter d'apprendre un nouveau langage de formatage, ils utilisent la sortie HTML qu'ils éditent comme modèle. Si vous saviez à quel point SGML est simple (et utile) avec LinuxDoc, vous comprendriez qu'apprendre les quelques balises supplémentaires nécessaires pour le formatage SGML vaut le coup.

Voilà pourquoi les sections suivantes introduiront les parties les plus importantes d'un fichier sgml LinuxDoc et comment étendre votre documentation.

## 9.3.1. La Déclaration de la DTD

Un fichier SGML, quelque soit la DTD utilisée, doit toujours commencer avec la déclaration de la DTD. Cela indique à l'analyseur syntaxique (NdT : parser) SGML comment doit être utilisée une DTD. C'est pourquoi, la première balise (une expression entre crochets, comme &<;votrebalise&>; votrecontenu &<;/votrebalise&>;) est toujours le DOCTYPE :

`&<;!doctype linuxdoc system&>;`

Cela indique au formateur sgml qu'il doit utiliser la DTD LinuxDoc.

### 9.3.1.1. La Structure du Document

Avec LinuxDoc, la balise suivante est la balise de début du type de style de document. La DTD LinuxDoc permet un ensemble complet de types que vous pouvez sélectionner, selon le but du document ou sa longueur. Les formats disponibles sont :

- `&<;notes&>;` pour de brèves explications& ;;

- `&<;article&>;` pour écrire des articles d'environ 10-20 pages (recommandé). Ceci est utilisé par les modèles de KDevelop et la plupart des applications KDE& ;;

- `&<;report&>;` pour des articles qui sont plus longs que le type &<;article&>;& ;;

- `&<;book&>;` pour écrire des livres plus longs - les manuels de KDevelop ont été rédigés en utilisant ce type de document& ;;

- `&<;slides&>;` pour des transparents. C'est utile pour des présentations. Bien sur, vous utiliserez le format de sortie LaTeX dans la plupart des cas& ;;

- `&<;letter&>;` pour des lettres classiques& ;;

- `&<;telefax&>;` pour un fax& ;;

- `&<;manpage&>;` pour une page de manuel (NdT : manpage).

Remarquez que ces formats décrivent seulement la structure globale du document - pas le format de sortie. Comme mentionné, le modèle de documentation de Kdevelop généré par défaut utilise la structure &<;article&>;. Elle est utilisée par la majorité des applications hormis KDevelop qui utilise le format &<;book&>;. Cela importe peu dans la sortie HTML mais pour le format LaTeX, la différence est plus nette. Les manuels sont vraiment des "livres" avec des pages séparées pour chaque chapitre (c'est la principale différence).

Enfin, la fin du fichier sgml doit avoir une balise fermante pour le type de structure de document - pour &<;article&>;, ce sera &</;article&>;.

## 9.3.2. Pages de Titre

La section qui suit la structure du document décrit toutes les entrées que l'on trouve généralement sur une page de titre. Le modèle prédéfini ne l'utilise pas explicitement mais définit seulement les informations pour `&<;title&>;`, `&<;author&>;` et `&<;date&>;` car cela convient dans la plupart des cas. Dans le cas spécial de la structure `&<;book&>;`, vous voudrez probablement définir une page de titre complète. Voici la liste des balises correspondantes tirée du source sgml de ce manuel :

       1 &<;!doctype linuxdoc system&>;
       2 &<;book&>;
       3 &<;titlepag&>;
       4 &<;title&>;The KDevelop Programming Handbook
       5 &<;subtitle&>;The User Guide to C++ Application Design for the K Desktop Environment (KDE) with the KDevelop IDE, Version 1.2
       6 &<;author&>;
       7 &<;name&>;Ralf Nolden &<;htmlurl url="mailto:Ralf.Nolden@post.rwth-aachen.de"
       8 								   name = "&<;Ralf.Nolden@post.rwth-aachen.de&>;"&>;
       9 &<;inst&>;The KDevelop Team
      10 &<;date&>;Version 1.2 , July 7, 1999
      11 &<;abstract&>;
      12 This handbook itself is part of the KDevelop Integrated Development Environment
      13 and is therefore also licensed under the GNU General Public License;
      14 see &<;ref id="Copyright" name="Copyright"&>; for more information.
      15 &</;abstract&>;

Ceci recouvre tout ce qu'une page de titre contient normalement. La balise `&<;author&>;` peut aussi inclure une balise `&<;thanks&>;` pour insérer des remerciements aux co-auteurs, relecteurs, etc. `&<;inst&>;` représente l'institut ou la société pour laquelle l'auteur a écrit la documentation ; vous pourriez aussi ajouter ici le nom de votre équipe, comme je l'ai fait. `&<;abstract&>;` contient une courte description qui est également placée sur la page de titre. Cela est un peu gênant pour les sorties imprimées où cette section serait imprimée au verso de la page de titre où sont regoupés le copyright, etc. ; cela peut être modifié dans la sortie au format LaTeX en éditant le fichier TeX.

## 9.3.3. Index

La DTD LinuxDoc définit un ensemble de balises pour les différents index qui apparaissent régulièrement dans les documents. Celles-ci sont :

- &<;toc&>; pour la table des matières

- &<;lof&>; pour la liste des figures

- &<;lot&>; pour la liste des tableaux

Les balises ouvrantes correspondantes ne nécessitent pas forcément une balise fermante ; elles sont insérées juste après la page de titre, avant le début du document avec les sections et chapitres correspondants.

Lorsque vous voulez indexer des mots-clés pour un glossaire qui est placé à la fin du document, vous disposez de 4 balises différentes ; deux qui laissent la phrase indexée dans la page et deux pour les entrées d'index qui ne sont pas affichées.

- &<;idx&>; pour une entrée d'index normale

- &<;cdx&>; pour une entrée d'index true-type

- &<;nidx&>; pour une entrée d'index n'apparaissant pas dans le document

- &<;ncdx&>; comme précédemment pour une entrée d'index tt

Ces balises sont ignorées par tous les moteurs (l'outil qui fait la correspondance des balises sgml avec leur format de document) excepté `sgml2latex` qui génère un fichier d'index `index.idx` qui peut être converti en fichier TeX-index avec `makeindex index.idx`. L'index en lui-même peut être inséré ultérieurement dans le fichier de sortie TeX avec `\printindex`. J'ai modifié (NdT : patché) ma correspondance pour la sortie LaTeX afin de la faire automatiquement (mais je ne sais toujours pas comment inclure l'index dans la table des matières...).

## 9.3.4. Le Contenu du Document

Après avoir expliqué la plupart des détails sur la structure générale, nous abordons le contenu réel du document. Suivant le type de structure du document, on trouve une balise `&<;sect&>;` si on utilise `&<;book&>;`, vous devez commencer vos chapitres par `&<;chapt&>;`.

Après la balise de début, vous pouvez structurer chaque chapitre avec `&<;sect1&>;`, `&<;sect2&>;` etc. jusqu'au nombre maximal de niveaux de sous-sections (4).

La balise ouvrante du chapitre est suivie par le titre de ce chapitre. Vous avez le choix d'utiliser `&<;title&>;` et `&</;title&>;` pour le titre du chapitre (optionnel). Ensuite, après le titre du chapitre, vous devez ajouter une balise &<;p&>; pour réellement commencer le contenu de la sous-section. Dans celle-ci, vous avez toutes les possibilités pour formater votre document avec des listes, des énumérations, des puces et des descriptions de listes. De plus, les citations, les extraits de code, etc peuvent être insérés avec des balises ; consultez le guide de documentation des `sgmltools` pour une liste complète. Vous pourrez en profiter pour regarder la section sur les "caractères spéciaux". Elle contient tous les remplacements valides pour les caractères hors des alphabets usuels comme les crochets, les barres obliques et les symboles comme la marque déposée etc. Avec ces balises, vous pouvez structurer le contenu du texte selon les besoins de la documentation de votre application.