|
Créer un fichier d'aide pour vos codesDate de publication : 15/12/2004 , Date de mise à jour : 19/12/2004
Par
Sébastien Doeraene (sjrd.developpez.com)
Détail de la norme Borland pour les fichiers d'aide expliquant du code objet
Présentation I. Fichiers d'aide en général II. Le modèle HelpFile.dot III. Légende IV. Généralités IV-A. Le titre IV-B. La note de bas de page # IV-C. La note de bas de page $ IV-D. La note de bas de page K IV-E. La note de bas de page A IV-F. La région fixe IV-F-1. Comment réaliser une région fixe IV-F-2. Syntaxe de la région fixe IV-G. Corps de la rubrique IV-G-1. Rubrique d'unité IV-G-2. Rubrique de classe IV-G-3. Autres types de rubrique IV-G-3.1. Paragraphe d'introduction IV-G-3.2. Syntaxe IV-G-3.3. Description V. Précisions par type de rubrique VI. Règles des liens Présentation
Vous avez un code source à distribuer et vous aimeriez que les utilisateurs de celui-ci
puissent bien comprendre leur utilité au moyen d'un fichier d'aide. Voici un tutoriel qui
vous aidera à bien réaliser ceux-ci.
Ce tutoriel détaille la norme Borland concernant les fichiers d'aide expliquant du code.
Ainsi, vous pourrez lier vos fichiers d'aide à l'aide de Delphi/C++ Builder pour qu'un
appui sur F1 dans l'éditeur se rapporte à votre aide.
Ce qui suit est décrit dans l'aide de Delphi et de C++ Builder mais les rubriques
correspondantes sont non seulement très difficiles à trouver mais en plus sont très
difficiles à comprendre. J'ai fait l'effort pour vous de les étudier et de tester ce qui
y est dit. Voici donc une théorie éclaircie sur le sujet.
I. Fichiers d'aide en général
Premièrement, si vous ne savez pas rédiger et compiler un fichier d'aide quelconque,
lisez ce tutoriel qui porte sur le sujet. Ce tutoriel vous explique en détails la création de fichiers d'aide au format .hlp, ainsi que ce que sont les notes de bas de page $, K, A, que vous ne connaîssez peut-être pas encore même si vous avez déjà réalisé des fichiers d'aide. II. Le modèle HelpFile.dot
Outre la théorie, il faut aussi de la pratique, mais dans ce cas la pratique est
implicitement donnée dans la pratique. Vous pouvez néanmoins utiliser le modèle Word
HelpFile.dot
(télécharger
ce moddèle), qui facilite énormément le travail. Si ce lien ne fonctionne pas, essayez celui-ci.
Pour créer une rubrique, cliquez sur le bouton correspondant dans la barre d'outil
Fichier d'aide. Sélectionnez alors un des boutons radio selon le type de rubrique
que vous souhaitez. Une boîte de dialogue apparaît alors. Remplissez les champs présents et validez. Le canevas de la rubrique et quelques données sont créés. Il ne vous reste plus qu'à écrire le reste.
III. Légende
Créez tout d'abord une rubrique pop-up de légende, semblable à celle qui s'affiche
lorsque vous cliquez sur le lien Légende des listes de routines/membres de
classes.
Si vous possédez le modèle HelpFile.dot, vous pouvez créer
cette rubrique avec le deuxième type de rubrique, à savoir pop-up.
Cette rubrique, du fait qu'elle est de type pop-up, ne doit comporter qu'une note de bas
de page #, celles $, K et A ne doivent pas être présentes. De même, le titre doit
uniquement être du simple texte mis en gras. L'identificateur peut par exemple être
MembersLegend (c'est ce que j'utilise).
IV. Généralités
Nous allons commencer par les généralités sur l'apparence des pages, la région
fixe, bref la présentation générale. Nous verrons aussi que tous les liens, excepté
les liens pop-up, doivent se faire avec les A-link, pour pouvoir accéder aux
rubriques réalisées par Borland ou d'autres développeurs ; et que les mots-clés K et A
doivent suivre des règles strictes, pour les liens dans l'autre sens, mais aussi pour la
touche magique F1.
IV-A. Le titre
Le titre doit toujours être de la forme suivante :
où NomElement est le nom de l'élément, comme TObject, MessageDlg ou
Show ; et typeElement est le type de l'élément, comme classe,
fonction ou méthode (TCustomForm). Vous aurez remarqué que dans le cas d'un membre d'une classe, il faut spécifier la classe correspondante entre parenthèses.
Nous verrons quels sont exactement les différents types possibles dans la
description des types de rubriques.
IV-B. La note de bas de page #
La note de bas de page # reste à votre entier choix. Cependant, afin d'éviter les
doublons, il serait sage d'utiliser le chemin complet d'accès à l'élément en
remplaçant les . par des _.
Voici un exemple pour la méthode Show de la classe TCustomForm, déclarée dans l'unité Forms :
IV-C. La note de bas de page $
Comme partout, la note de bas de page $ doit avoir le même texte que
le titre.
IV-D. La note de bas de page K
Nous allons commencer à voir ce qui est réellement important. En effet, les notes de bas
de page K et A sont très importantes pour la touche F1 et pour les liens.
Les notes de bas de page K sont utilisées par la touche F1, aussi bien de l'éditeur de
code que de l'inspecteur d'objet.
Pour les propriétés, méthodes et événements de classes, les notes de bas de page K
doivent être de la forme suivante :
Où NomElement est le nom de l'élément (par exemple Show) ; NomClasse
est le nom de la classe qui le définit (par exemple TCustomForm) ; et
TypeElement est le type de l'élément, soit Property (pour les propriétés),
Method (pour les méthodes) ou Event (pour les événements).
Pour les autres éléments, la note de bas de page K doit juste être le nom de l'élément.
Par exemple :
IV-E. La note de bas de page A
Pour ce qui est des notes de bas de page A, elles diffèrent beaucoup d'un type de
rubrique à l'autre. Nous verrons donc leur syntaxe dans la
définition des types de rubrique.
IV-F. La région fixe
La région fixe, c'est la ligne de texte sous le titre qui ne bouge pas même
lorsque l'utilisateur fait défiler le texte.
IV-F-1. Comment réaliser une région fixe
Intéressons-nous d'abord à la façon de réaliser cette région fixe. En effet, nous n'avons
pas vu cette astuce dans le tutoriel sur la création de fichiers HLP.
Si vous utilisez le modèle HelpFile.dot, il suffit de placer,
en-dessous du titre, un paragraphe dont le style est Région fixe.
Si vous n'utilisez pas ce modèle, vous devrez créer vous-même ce style. En effet un
paragraphe est considéré comme étant dans la région fixe si il est d'un style marqué
Titre (1~9). Dans Word, choisissez le menu Format|Style.... Cliquez sur le bouton Nouveau.... Remplissez les champs comme ici : (n'oubliez pas la case à cocher Ajouter au modèle) 
Cliquez ensuite sur le bouton Format, puis sur Paragraphe.... Dans la
fenêtre qui s'affiche, dans l'onglet Retrait et espacement, choisissez
Titre 9 dans la liste déroulante nommée Niveau hiérarchique. Cliquez sur OK ou Appliquer pour fermer toutes les boîtes de dialogue. IV-F-2. Syntaxe de la région fixe
La syntaxe de la région fixe dépend beaucoup du type de rubrique. Cependant elle doit
toujours commencer par un lien vers l'unité déclarant l'élément (à moins bien sûr que ce
ne soit une rubrique d'unité) et se terminer, si vous le désirez, par un lien de type
Voir aussi.
Nous verrons dans la description des types de rubrique les
détails concernant ce qui doit figurer dans la région fixe.
IV-G. Corps de la rubrique
Le corps de la rubrique change en fonction du type de rubrique. Il n'y a cependant que
trois canevas. Nous allons donc les voir ici.
IV-G-1. Rubrique d'unité
Dans les rubriques d'unité, le corps doit commencer par un paragraphe d'introduction,
indiquant les éléments les plus intéressants de l'unité, etc.
Ensuite vient la liste complète de tous les éléments de l'unité.
Utilisez des Titre 2 pour les titres. N'oubliez pas de suivre les règles des liens. IV-G-2. Rubrique de classe
Pour une rubrique de classe, le corps de la rubrique n'est que du texte de description du
fonctionnement général de la classe, de son utilité, avec des
liens vers les propriétés/méthodes clés.
IV-G-3. Autres types de rubriqueIV-G-3.1. Paragraphe d'introduction
En-dessous de la région fixe doit se trouver un paragraphe d'introduction. Les
raisons en sont détaillées dans le tutoriel sur la création de fichiers HLP.
Ce doit être une simple ligne donnant en le moins de mots possible l'utilité de
l'élément.
IV-G-3.2. Syntaxe
Ensuite vient la syntaxe de l'élément.
Si vous développez vos sources en Delphi et C++, vous devez utiliser deux syntaxes, la
première pour la syntaxe Delphi et la suivante pour la syntaxe C++ (c'est pas parce que
je préfère Delphi, c'est comme ça dans l'aide Borland).
Si vous ne développez que dans un langage, vous pouvez vous contenter de mettre :
Utilisez un Titre 3 pour les titres et une police à pas fixe pour la syntaxe. N'oubliez pas de mettre en gras les mots clés. IV-G-3.3. Description
Terminez par un texte de description détaillé de l'élément, de ses paramètres (routine,
méthode ou événement), etc.
Utilisez un Titre 3 pour le titre Description.
V. Précisions par type de rubrique
Nous allons maintenant voir les caractéristiques spécifiques à chaque type de rubrique.
VI. Règles des liens
Tous les liens dans les corps de rubriques doivent être des liens de type A-link.
De plus, utilisez toujours la destination la plus précise possible. Par exemple, si vous
voulez atteindre la méthode Show de la classe TCustomForm, utilisez comme
destination TCustomForm_Show plutôt que Show, car cette deuxième
possibilité vous mènerait aussi vers TControl.Show.
Si vous ne savez pas faire de liens de type A-link, consultez le tutoriel
Créer un fichier HLP.
Warning: include(): http:// wrapper is disabled in the server configuration by allow_url_include=0 in /home/developpez/www/developpez-com/upload/sjrd/windows/tutoriel/codehelp/index.php on line 521 Warning: include(http://sjrd.developpez.com/references.inc): failed to open stream: no suitable wrapper could be found in /home/developpez/www/developpez-com/upload/sjrd/windows/tutoriel/codehelp/index.php on line 521 Warning: include(): Failed opening 'http://sjrd.developpez.com/references.inc' for inclusion (include_path='.:/opt/php56/lib/php') in /home/developpez/www/developpez-com/upload/sjrd/windows/tutoriel/codehelp/index.php on line 521 |
Copyright © 2005 Sébastien Doeraene. Aucune reproduction, même partielle, ne peut être faite de ce site ni de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.
