Warning: filemtime(): stat failed for /home/developpez/www/developpez-com/upload/sjrdhttp://sjrd.developpez.com/stylesheet.css in /home/developpez/www/developpez-com/template/entete.php on line 405
IdentifiantMot de passe
Loading...
Mot de passe oublié ?Je m'inscris ! (gratuit)

Créer un fichier d'aide pour vos codes

Date 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
warning Cet article est en cours de rédaction et n'est donc pas terminé.

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.

warning Les constantes ne fonctionnent pas encore. Utilisez pour cela un type puis modifiez les notes de bas de page et titre d'après la théorie ci-après.

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 :

NomElement, typeElement
				
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 :

# Forms_TCustomForm_Show
				

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 :

NomElement;NomClasse_NomElement;NomElement_TypeElement
				
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 :

MessageDlg
				

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

Paragraphe d'introduction

Exceptions
Liste des exceptions

Types
Liste des types

Variables
Liste des variables

Classes
Liste des classes

Routines
Liste des routines

Constantes
Liste des constantes
					
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 rubrique


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

Syntaxe Delphi
TMonType = (mt1, mt2);

Syntaxe C++
enum TMonType {mt1, mt2};
						
Si vous ne développez que dans un langage, vous pouvez vous contenter de mettre :

Syntaxe
TMonType = (mt1, mt2);
						
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.

Description
Texte de description.
						
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

Valid XHTML 1.1!Valid CSS!

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.