# Chapitre 9. Extension de la Documentation avec SGML

Du fait que les projets manquent souvent d'un manuel d'utilisation complet, tous les projets KDevelop contiennent un manuel pré-construit qui peut facilement être adapté ; un autre des objectifs de KDE est ainsi rempli : fournir suffisamment d'aide en ligne pour guider les utilisateurs qui ne sont pas habitués à une application. Ce chapitre vous explique donc comment étendre le modèle de documentation fourni et ce que vous devez faire pour le rendre disponible à l'utilisateur.

# 9.1. Pourquoi SGML ?

SGML (Standard Generalized Markup Language) est un langage avec lequel on peut écrire les spécifications d'un langage de marquage mais n'est pas un langage de marquage en lui-même. La spécification de ce langage de marquage est appelée une DTD (Document Type Definition) qui contient la structure d'un document et les balises valides utilisables. Ensuite, un système SGML fournit un ensemble de fichiers de remplacement qui traduisent les balises de la DTD dans le format de sortie désiré - et c'est de cette façon que cela fonctionne. Le format de sortie le plus utilisé est probablement HTML pour fournir de l'aide en ligne à travers des serveurs web, à une époque où les standards de l'Internet sont accessibles même depuis des systèmes à un seul bureau. KDE utilise intensivement la documentation HTML aussi bien par le biais de son application KDEHelp où toutes les applications KDE sont listées et qui donne accès à leurs manuels d'utilisation que par le menu d'aide qui permet, depuis une application, d'accéder directement à l'aide en ligne.

Actuellement, KDE (et par conséquent KDevelop) utilise le paquetage des SGML-Tools 1.x (voir \|\|) qui était connu sous le nom de paquetage LinuxDoc. Il contient une DTD appelée `LinuxDoc` et un ensemble de fichiers de correspondance pour différents formats de sortie, ainsi que les outils nécessaires pour réaliser effectivement le remplacement des balises `LinuxDoc`. La DTD LinuxDoc est basée sur la DTD Qwertz qui, elle-même, avait été écrite afin de fournir une bonne correpondance (remplacement de balises), spécialement pour le système de traitement de texte LaTeX, et qui permet donc de produire des impressions de bonne qualité. Le paquetage a ensuite tiré son nom de l'utilisation qui en a été faite pour écrire les documentations du LDP (Linux Documentation Project) et a ensuite changé de nom parce que c'est un système sgml qui n'a pas nécessairement de rapport avec le projet Linux mais peut être utilisé sur n'importe quel système Unix. Vous pourriez aussi écrire votre propre DTD et vos correspondances si le coeur vous en dit.

Pendant ce temps, une autre DTD a vu le jour pour remplir les mêmes objectifs : la "DTD DocBook". DocBook a évidemment de nombreux avantages sur la DTD LinuxDoc, notamment en offrant de meilleures balises et correspondances pour les tables et l'insertion de graphiques mais cela reste aussi possible avec LinuxDoc. C'est pourquoi, les SGML-Tools ont basculé afin de fournir le support de la DTD DocBook dans la série des versions 2.x, qui inclut aussi un convertisseur produisant un sgml DocBook à partir d'un original LinuxDoc.

Dans l'état actuel du développement de KDE, nous utilisons encore la DTD LinuxDoc pour certaines raisons :

- écrire de la documentation LinuxDoc est facile

- installer les SGML-Tools 1.x permettant d'utiliser LinuxDoc est encore plus simple

- KDE fournit un outil supplémentaire appelé `ksgml2html` qui ajoute le style de documentation KDE à la sortie générée par le convertisseur `sgml2html` des SGML-Tools 1.x afin de produire une sortie HTML.

J'ai personnellement remarqué, pendant l'écriture des manuels de Kdevelop, qu'utiliser la DTD LinuxDoc est très facile et s'accorde bien avec les besoins que j'avais pour écrire la documentation. Le rythme d'apprentissage est très rapide et en quelques jours, vous serez devenu un expert de sgml-tools/DTD LinuxDoc, ce qui vous épargnera le temps que vous auriez passé à apprendre un système de formatage comme TeX pour les sorties papier de votre documentation ou un langage à balise pour les sorties HTML.

Une raison majeure de continuer à utiliser les sgml-tools 1.x est que la plupart des distributions contiennent ce paquetage et tous les outils nécessaires pour d'autres formats de sortie. Cela rend l'installation aussi simple que possible et l'écriture en elle-même n'est pas très compliquée, vous allez le voir. Les formats de sortie que vous pouvez obtenir avec les sgml-tools sont :

- HTML avec l'apparence KDE si vous utilisez `ksgml2html`

- texte brut

- GNU info

- format Lyx

- formats TeX, DVI, PostScript et PDF

- Rich Text Format (RTF).