Le Manuel de Programmation de KDevelop: Extension de la Documentation avec SGML

Page suivante Page précédente Table des matières

### 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 http://www.sgmltools.org) 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).

### 9.2 Ce que la Documentation contient déjà

Lors de la création d'un projet KDevelop, le répertoire `docs/en` contient déjà le fichier de documentation en anglais `index.sgml` et les fichiers résultant de la génération au format HTML. Ceux-ci sont déjà inclus dans le projet et l'emplacement d'installation est prédéfini au répertoire HTML de KDE. La documentation est déjà adaptée au nom de votre projet, son numéro de version et les informations sur le programmeur. En plus, la sortie génère le fichier index.html qui contient la table des matières (qui est ouverte par l'Aide de KDE quand l'utilisateur demande de l'aide) ; une introduction à l'installation et des informations sur le copyright en relation avec la Licence GPL sont incluses.

Par conséquent, lorsque vous étendez la documentation, vous devez seulement ajouter les informations qui sont spécifiques à votre projet. Notez que pour les projets KDE, vous devez exécuter "Construire le manuel d'utilisation" dans le menu "Projet" après la création du projet. Le fichier index.sgml est à nouveau traité par `ksgml2html` et le style KDE est ajouté à la sortie HTML. Ouvrez le dossier `docs/en` dans l'onglet RFV et ajoutez le fichier `logotp3.gif` au projet via le menu contextuel ; définissez ensuite correctement les propriétés du fichier afin qu'il s'installe au même endroit que les fichier HTML - dans `$(kde_htmldir)/en/<votre_projet>/logotp3.gif`.

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

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

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

#### 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 :

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

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

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

### 9.4 Comment appeler l'Aide dans les Boîtes de Dialogue

Dans les boîtes de dialogue, on appelle souvent l'aide en ajoutant un bouton "Aide" ; ensuite, vous ajoutez un slot qui est appelé lorsque le bouton est enfoncé. Dans l'implantation du slot, appelez

> `

>     kapp->invokeHTMLHelp( QString aFilename, QString aTopic );

> `

où `aFilename` est le nom du fichier à appeler dans le dossier de la documentation HTML de votre application ; par exemple, index-3.html. Ensuite, `aTopic` est la section à appeler. Le préfixe de hachage est ajouté automatiquement ; saisissez juste le chapitre que vous voulez avoir sur cette page, en fait, cela peut être le nom d'une sous-section.

Page suivante Page précédente Table des matières