Créer un fichier d'aide HLP

Sébastien Doeraene

Réaliser un fichier d'aide au format HLP ♪

- Titre : Créer un fichier d'aide HLP

- Auteur : Sébastien Doeraene

- Parution : 23 octobre 2004

- Mise à jour : 28 octobre 2004

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2005 Sébastien Doeraene. Aucune reproduction, même partielle, ne peut être faite de ce site et 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.

Sommaire

- I. Présentation

- I-A. Pourquoi utiliser le format HLP ?

- I-B. Qu'est-ce que Microsoft Help Workshop ?

- I-C. Qu'est-ce que WinHelp ?

- I-D. De quoi ai-je besoin ?

- I-E. Modèle Word HelpFile.dot

- II. Architecture et contenu en large du fichier d'aide

- II-A. Comment choisir une bonne architecture ?

- III. Rédaction des fichiers RTF

- III-A. Notions théoriques

- III-A-1. Différentes rubriques

- III-A-2. Mot-clés K et mot-clés A

- III-A-3. La région fixe

- III-A-4. Liens entre les rubriques

- III-B. Mise en pratique avec DemonstrHLP.rtf

- III-B-1. Création du fichier

- III-B-2. Page d'accueil

- III-B-3. Page de sommaire

- III-B-4. Pages du contenu

- III-B-5. Enregistrement

- III-C. Ajouts possibles pour des pages plus complexes

- III-C-1. Images

- III-C-2. Rubriques de type pop up

- III-C-3. Autres options de Help Workshop

- III-D. Rédaction des fichiers RTF terminée

- IV. Création du fichier de projet d'aide

- IV-A. Création du fichier

- IV-B. L'indispensable

- IV-B-1. Fichiers RTF utilisés

- IV-B-2. Rubrique par défaut

- IV-B-3. Première compilation

- IV-C. Les améliorations

- IV-C-1. Informations globales

- IV-C-2. Chemins des images

- IV-C-3. Carte du fichier d'aide

- IV-C-4. Autres fonctions de Help Workshop

- IV-D. Compilation et premier test

- V. Création du fichier de sommaire

- V-A. Création du fichier

- V-B. Réalisation du sommaire

- V-C. Réglages supplémentaires

- V-D. Le fichier d'aide est complètement terminé

- VI. Tester le fichier d'aide

- VII. Fin de ce tutoriel

- VII-A. Clôture du tutoriel

- VII-B. Liens

- VII-C. Remerciements

I - Présentation

Vous avez créé un superbe programme, fonctionnel, intuitif, puissant, mais vous recevez régulièrement des e-mails vous demandant comment utiliser votre logiciel. Vous n'avez sans doute pas pensé à réaliser un fichier d'aide pour accompagner celui-ci. Voici un tutoriel qui va vous aider à en réaliser un en utilisant Microsoft Help Workshop, logiciel distribué avec toutes les éditions de Delphi.

Cet article a été initialement conçu pour les utilisateurs de Delphi, ceci explique que plusieurs allusions à Delphi soient faites.

I-A - Pourquoi utiliser le format HLP ?

Le format HLP est dit obsolète par rapport au format CHM, mais, regardez l'aide de Delphi, ce sont quand même des fichiers au format HLP. Ceci pour une bonne raison : on peut plus facilement accéder à un fichier HLP depuis Delphi qu'à un fichier CHM et on peut même commander un fichier HLP avec Delphi (voir les méthodes et propriétés s'y rapportant dans l'objet TApplication). De plus, je persiste à croire qu'éditer un fichier RTF est plus facile que d'éditer un fichier HTML et je pense ne pas être le seul.

I-B - Qu'est-ce que Microsoft Help Workshop ?

Pour réaliser les fichiers d'aide, vous aurez besoin du logiciel Microsoft Help Workshop, distribué avec toutes les éditions de Delphi. Ce logiciel permet de réaliser non seulement le fichier .hlp, mais également le sommaire au format .cnt (pour contents). Notez que ce logiciel est en anglais. Nous décrirons son utilisation tout au long de ce tutoriel.

I-C - Qu'est-ce que WinHelp ?

WinHelp est distribué avec Windows. C'est le programme qui permet à tout un chacun de consulter les fichiers d'aide au format .hlp.

I-D - De quoi ai-je besoin ?

Outre le programme Help Workshop, vous avez besoin d'un éditeur de fichiers .rtf (Rich Text Format). Par exemple Microsoft Word sera parfait. Je supposerai dans ce tutoriel que vous utilisez Word. Si cependant vous utilisez un autre éditeur, vous n'aurez probablement aucun mal à transposer les opérations décrites, à moins que votre éditeur ne supporte pas les styles Titre, le soulignement double ou le texte masqué.

I-E - Modèle Word HelpFile.dot

Si vous utilisez Microsoft Word comme éditeur RTF, vous pouvez utiliser le modèle HelpFile.dot pour créer vos fichiers RTF. J'ai réalisé ce modèle dans le but de réaliser des fichiers d'aide avec Microsoft Help Workshop. Il vous facilitera la vie en accélérant l'édition de vos fichiers .rtf.
Si ce lien ne fonctionne pas, essayez celui-ci.

II - Architecture et contenu en large du fichier d'aide

La première phase ne se passe pas devant l'écran de votre PC. Vous devez avant tout décider du contenu de votre fichier d'aide ainsi que de son architecture. Notez l'architecture et quelques mot-clés pour chaque rubrique sur une feuille de papier. Cette phase semble simple, mais il est tout de même important de choisir une bonne architecture.

II-A - Comment choisir une bonne architecture ?

Dans un fichier d'aide, il doit y avoir une rubrique (page) d'accueil, une rubrique de sommaire et une rubrique pour chaque élément de l'application. Pour ce tutoriel, nous utiliserons un petit programme dont les sources sont disponibles dans le zip d'exemple (le télécharger). Voici une capture d'écran de ce logiciel :

Il faudra donc une rubrique pour les nom et prénoms, une deuxième pour le surnom, une troisième pour le numéro de téléphone, et une dernière pour la date de naissance (sans oublier la rubrique d'accueil et celle de sommaire). La hiérarchie (l'architecture si vous préférez) ressemble à ceci :

Accueil
Sommaire
Utilisation du programme
Nom et prénoms
Surnom
Numéro de téléphone
Date de naissance

- La page d'accueil doit présenter le programme, proposer un lien vers la page sommaire et éventuellement présenter le ou les auteur(s).

- La page de sommaire doit présenter un lien vers chacune des pages principales du projet (ici toutes).

- Le sous-titre Utilisation du programme ne correspond à aucune rubrique : c'est un sous-titre dans la table de sommaire. Nous verrons la création de la table de sommaire à l'étape V.

- Les quatre dernières rubriques doivent expliquer l'utilisation des contrôles respectifs (dans ce cas-ci).

Maintenant que notre architecture est mise en place et que nous savons ce que devra comporter chacune des rubriques, nous pouvons passer à l'étape de réalisation des fichiers RTF.

III - Rédaction des fichiers RTF

Voici la phase la plus longue, mais aussi la plus importante. Il s'agit de la rédaction des fichiers RTF, c'est-à-dire la rédaction du texte de l'aide.

III-A - Notions théoriques

Vous devez utiliser un ou plusieurs fichiers au format RTF (Rich Text Format) qui vont définir tout le contenu de l'aide. Vous pouvez éditer ces fichiers avec n'importe quel éditeur de texte supportant ce format de fichier.
Si vous utilisez Microsoft Word et que vous utilisez le modèle HelpFile.dot, vous bénéficierez d'une énorme simplicité pour la rédaction. Tout au long de cet article je proposerai deux méthodes : l'une sans ce modèle Word, l'autre, plus simple, avec celui-ci.

III-A-1 - Différentes rubriques

Chaque rubrique doit être séparée par un saut de page manuel. Le titre de la rubrique doit être dans un style marqué Titre, excepté pour les rubriques dites « pop up » (1). Par exemple Titre 1. Devant le titre, il doit y avoir une note de bas de page marquée # dont le texte est un identificateur unique pour la rubrique. Peuvent également apparaître, mais ne sont pas obligatoires, les notes de bas de pages marquées $, K, A dont le texte équivaut respectivement au titre de la rubrique (tel qu'il apparaît dans les fenêtres de WinHelp), les mot-clésK et les mot-clés A. Dans une rubrique pop up, seule la note de bas de page marquée # peut être présente.

III-A-2 - Mot-clés K et mot-clés A

Commençons par les mot-clés K. Ces mot-clés permettent à WinHelp de générer un index (uniquement si vous réalisez un fichier de table de sommaire, que nous étudierons à l'étape V) et servent également pour les sauts de types K-link (ils seront généralement utilisés uniquement pour l'index). Plusieurs mot-clés K peuvent être indiqués en les séparant par des points-virgules (;). Chaque mot-clé K se retrouvera dans l'index avec pour rubrique associée la rubrique dans laquelle il est défini (plusieurs rubriques peuvent avoir un même mot-clé K). En séparant deux parties d'un mot-clé K avec une virgule (,), la deuxième se placera indentée sous la première et seule la deuxième sera reliée à la rubrique.

Les mot-clés A sont semblables aux mot-clés K à la différence qu'ils ne sont pas inclus dans l'index est qu'ils sont utilisés par les sauts de type A-link.

Nous décrirons les sauts de types K-link et A-link dans la section Liens entre les rubriques

III-A-3 - La région fixe

La région fixe est une courte zone placée en début de chaque rubrique, et qui ne scrolle pas. Elle est destinée à accueillir le titre bien entendu.

Il est indispensable de placer un paragraphe d'introduction juste après le titre de la rubrique. En effet, si vous placez directement un sous-titre juste en dessous du titre, il sera inséré également dans la région fixe.

Vous pouvez toutefois vous servir de cette région fixe pour y placer également une série de liens. Dans ce cas, vous pouvez soit utiliser un « sous-titre » (à la bourrin), soit modifier directement la source de l'inclusion dans la région fixe, à savoir la solidarité des paragraphes. Pour qu'un paragraphe placé juste en dessous du titre apparaisse dans la région fixe, il suffit, dans la boîte de dialogue Format|Paragraphe, onglet Enchaînements, de cocher la case Paragraphes solidaires.

III-A-4 - Liens entre les rubriques

Dans le corps de la rubrique peuvent se trouver des liens vers les autres rubriques. Dans le cas d'un saut normal, le texte du lien doit être en double souligné et l'identificateur (spécifié via la note de bas de page #) de la rubrique de destination en masqué accolé au texte de la rubrique. Dans le cas d'un saut vers une rubrique pop up, le texte du lien doit être en simple souligné. Pour les sauts de type K-link et A-link (qui utilisent respectivement les mot-clés K et A des rubriques de destination), le texte du lien doit être en double souligné, mais la destination de la rubrique (toujours en masqué et accolée au texte) doit être de la forme suivante.

Syntaxe de la destination d'un lien K-link

!KLink(MotCle[;MotCle2[;MotCle3[;...]]], 1)

Syntaxe de la destination d'un lien A-link

!ALink(MotCle[;MotCle2[;MotCle3[;...]]], 1)

Où les mot-clés sont un ou plusieurs des mot-clés K (dans le cas d'un saut de type K-link) ou A (dans le cas d'un saut de type A-link) présents dans la ou les rubrique(s) de destination. Le 1 spécifie que si WinHelp trouve une seule rubrique, il l'affiche automatiquement tandis que s'il trouve plusieurs rubriques, il affiche une boîte de dialogue permettant à l'utilisateur de sélectionner une des rubriques trouvées.

III-B - Mise en pratique avec DemonstrHLP.rtf

Tout ceci vous paraît sans doute compliqué. Nous allons donc réaliser le fichier DemonstrHLP.rtf ensemble afin que vous mettiez en pratique ces notions très théoriques.

Comme dit plus avant, j'expliquerai toutes les manipulations telles qu'il faut les effectuer avec Microsoft Word. D'autre part, je donnerai une méthode sans le modèle Word HelpFile.dot et une autre, plus simple, avec celui-ci.

III-B-1 - Création du fichier

Commençons par créer le fichier. Si vous disposez du modèle HelpFile.dot, créez votre fichier à partir de ce modèle puis supprimer tout le contenu, sinon, créez-le à partir du modèle Normal. Enregistrez-le tout de suite sous le nom de votre choix, en toute logique dans le dossier de votre projet.

III-B-2 - Page d'accueil

Si vous possédez le modèle HelpFile.dot, sélectionnez le menu « Fichier d'aide|Nouvelle rubrique » (commande aussi disponible dans la barre d'outils Fichier d'aide). Choisissez le type Rubrique normale puis cliquez sur Continuer. Dans la boîte de dialogue suivante, entrez un identificateur unique pour la rubrique (avec les caractères alphanumériques de base, soit ['A'..'Z', 'a'..'z', '0'..'9', '_'] et qui ne commence pas par un chiffre), choisissons Accueil ; entrez ensuite le titre de la rubrique : Aide ; puis les mot-clés K (optionnel, mot-clés utilisés pour construire l'index de l'aide et par les liens K-link) : Accueil. Enfin les mots-clés A (optionnel, utilisés par les liens A-link) : Accueil également. Cliquez sur OK, votre rubrique est alors automatiquement crée (titre et notes de bas de page). Effacez le texte écrit automatiquement « Contenu de la rubrique ».

Si vous ne possédez pas le modèle HelpFile.dot, sélectionnez le style Titre 1, insérez quatre notes de bas de page dans l'ordre suivant : note marquée # dont le texte est « Accueil » (sans les guillemets bien sûr ; c'est l'identificateur unique de la rubrique), une autre marquée $ dont le texte est « Aide » (le titre que connaît, mieux vaut que ce soit le même que le titre que vous taperez ensuite) et deux autres marquées respectivement K et A dont le texte est « Accueil » (mot-clés K et A respectivement). Tapez ensuite le titre : « Aide » et un caractère paragraphe (touche Entrée, ou Enter pour les Belges).

Cette méthode sera appliquée pour chaque nouvelle rubrique.

Tapez ensuite un texte d'introduction à votre programme. Finissez par un lien vers la page de sommaire. Comment créer un lien ? Nous allons voir ça.

Si vous possédez HelpFile.dot, sélectionnez le menu « Fichier d'aide|Insérer un lien » (les trois autres menus servent à créer des liens vers une rubrique pop up, un lien « K-link » et un lien « A-link » respectivement). Entrez ensuite le texte du lien, c'est-à-dire « Sommaire » puis cliquez sur OK ; entrez enfin la destination du lien (l'identificateur de la rubrique de destination), « Sommaire » également, et cliquez sur OK. Le lien est automatiquement créé.

Si vous ne possédez pas HelpFile.dot, sélectionnez le menu « Format|Police » et passez en double souligné, cliquez sur OK. Tapez ensuite le texte du lien, soit « Sommaire » ici. Sélectionnez à nouveau le menu « Format|Police », supprimez le soulignement et placez l'attribut Masqué, puis cliquez sur OK. Tapez maintenant la destination du lien (l'identificateur de la rubrique de destination), « Sommaire » ici aussi. Supprimez l'attribut masqué avant de poursuivre votre frappe.

Nous avons terminé la page d'accueil. Placez-vous à la fin de la rubrique et tapez Ctrl+Entrée pour insérer un saut de page manuel, qui, je vous le rappelle, marque la séparation entre deux rubriques.

III-B-3 - Page de sommaire

Créez une nouvelle rubrique dont l'identificateur, le titre et les mot-clés K et A sont tous « Sommaire ». Le contenu de cette rubrique consistera uniquement en un lien vers chacune des quatre rubriques décrivant les quatre entrées du programme. N'oubliez pas le saut de page manuel à la fin.

III-B-4 - Pages du contenu

Remplissez les pages du contenu comme vous voulez, mais vous devez en avoir quatre : une pour chacun des éditeurs du programme : Nom et prénoms, Surnom, Téléphone et Date de naissance.

III-B-5 - Enregistrement

N'oubliez pas d'enregistrer votre fichier RTF. Le zip d'exemple (le télécharger) contient le fichier .rtf utilisé. Vous comprendrez peut-être mieux en l'examinant certains passages de ce tutoriel.

III-C - Ajouts possibles pour des pages plus complexes

III-C-1 - Images

Il y a deux moyens d'insérer des images dans un fichier d'aide. Soit vous insérer directement l'image dans le fichier RTF, ce qui est plus facile pour la lecture et la maintenance de ce fichier, mais qui alourdit le fichier d'aide généré si l'image en question se retrouve plusieurs fois dans l'aide.

L'autre façon est d'insérer dans le fichier RTF une ligne du type suivant.

Syntaxe d'insertion d'une image

{bmx[t] NomFichier.ext}

Dans ce code, x indique l'emplacement d'alignement du bitmap ; t, s'il est présent, indique que la couleur blanche dans le bitmap devra être considérée comme transparente ; et NomFichier.ext le nom du fichier (sans chemin) du bitmap, les extensions supportées sont .bmp, .shg, et .mrb.

Les valeurs possibles pour x sont :

- c : l'image est alignée dans le texte comme si c'était un caractère ;

- l : l'image est alignée sur la marge gauche et le texte continue à s'afficher sur sa droite ;

- r : l'image est alignée sur la marge droite et le texte continue à s'afficher sur sa gauche.

Le chemin du fichier image ne doit pas être spécifié. Nous verrons dans l'étape suivante que les chemins des bitmaps insérés de cette façon doivent être spécifiés dans la boîte de dialogue Bitmaps de Help Workshop.

III-C-2 - Rubriques de type pop up

Une rubrique de type pop up, ou hot spot, est une mini rubrique qui s'affiche au-dessus des autres fenêtres lorsque l'utilisateur clique sur un lien souligné en tirets discontinus. Les hot spots sont utilisés en général pour des définitions de termes se trouvant dans une autre rubrique. Pour qu'un lien affiche la rubrique de destination en pop up, le texte du lien doit être en simple souligné plutôt qu'en double. Avec le modèle HelpFile.dot, vous pouvez insérer un lien vers une rubrique pop up en utilisant le menu « Fichier d'aide|Insérer lien pop up » et créer une rubrique de ce type en utilisant la deuxième option de la boîte de dialogue « Nouvelle rubrique ».

III-C-3 - Autres options de Help Workshop

Microsoft Help Workshop propose beaucoup d'autres possibilités, pour lesquelles vous pourrez obtenir des informations dans l'aide, en anglais, de ce logiciel.

III-D - Rédaction des fichiers RTF terminée

Nous avons terminé la réalisation du fichier RTF. Nous allons pouvoir créer le fichier de projet d'aide (*.hpj).

IV - Création du fichier de projet d'aide

Vous allez maintenant apprendre à utiliser Help Workshop pour créer le fichier d'aide proprement dit. Lancez donc Help Workshop.

IV-A - Création du fichier

Sélectionnez le menu « File|New ». Dans la boîte de dialogue qui apparaît, sélectionnez « Help Project » (projet d'aide) puis cliquez sur OK. Choisissez un fichier dans lequel enregistrer les données du projet d'aide (par exemple le même nom que votre fichier d'aide, mais avec l'extension .hpj, dans le dossier principal de votre programme). S'affiche alors une fenêtre permettant d'éditer le contenu de votre projet d'aide.

IV-B - L'indispensable

Commençons par l'indispensable, soit les fichiers RTF utilisés, et la rubrique par défaut.

IV-B-1 - Fichiers RTF utilisés

Cliquez sur le bouton « Files » dans la partie droite de la fenêtre. La boîte de dialogue « Topic Files » s'affiche. Vous devez y spécifier tous les fichiers RTF à inclure dans votre fichier d'aide. Initialement la liste est vide. Cliquez sur le bouton « Add… » pour y ajouter le seul fichier RTF de notre aide. Dans la boîte de sélection de fichier, sélectionnez le fichier créé dans la phase Rédaction des fichiers RTF. Cliquez sur OK pour retourner à la fenêtre principale de Help Workshop.

IV-B-2 - Rubrique par défaut

Vous devez aussi spécifier la rubrique par défaut de votre fichier d'aide (ici la rubrique Accueil). Cliquez donc sur le bouton « Options ». Dans la zone étiquetée « Default topic », indiquez « Accueil ». Cliquez enfin sur OK.

IV-B-3 - Première compilation

Vous pouvez dès à présent cliquer sur le bouton « Save and Compile ». Une fenêtre nommée Compilation1 s'ouvre avec les éventuelles erreurs, avertissements et notes. En principe, vous ne devriez avoir que des avertissements du type « Non scrolling region defined after scrolling region » (dont vous ne devez absolument pas tenir compte) et des notes du type « Table cells borders non supported… » (dont vous ne devez pas tenir compte non plus). Vous pouvez maintenant ouvrir le fichier HLP créé dans le même répertoire que le fichier .hpj et vous pouvez admirer le résultat : vous pouvez naviguer parmi les rubriques grâce aux liens.

IV-C - Les améliorations

Tout ceci est très joli, mais il est toujours impossible de commander ce fichier d'aide directement depuis notre application Delphi. Nous allons donc régler quelques autres petits détails.

IV-C-1 - Informations globales

Cliquez à nouveau sur le bouton « Options ». Dans la zone « Help title », indiquez un titre pour votre aide, ce titre sera indiqué dans la barre de titre de la fenêtre principale de . Vous pouvez par exemple choisir « Aide de DemonstrHLP ». Dans la zone « Copyright information », les deux zones de texte représentent respectivement le texte à afficher dans la boîte de dialogue « Version » de et le texte à afficher si l'utilisateur tente de copier ou d'imprimer votre aide (la deuxième, si elle est non vide, empêche l'utilisateur de copier le texte de votre aide ; si elle est vide, l'utilisateur peut copier ou imprimer du texte ou des images dans votre aide). Pour des informations sur les autres pages de la boîte de dialogue Options, consultez l'aide de Help Workshop.

IV-C-2 - Chemins des images

Si vous avez inséré des images dans les fichiers RTF avec la syntaxe {bmx[t] NomFichier.ext}, vous devez maintenant spécifier les chemins vers ces images. Cliquez alors sur le bouton « Bitmaps » puis sur « Add » pour chaque chemin.

IV-C-3 - Carte du fichier d'aide

Nous allons maintenant créer une « carte » de votre fichier d'aide pour pouvoir accéder directement à toutes les rubriques depuis notre programme Delphi. Cliquez donc sur le bouton « Map ». Pour chaque rubrique, cliquez sur le bouton « Add ». Dans la boîte de dialogue qui s'affiche, indiquez l'identificateur unique de la rubrique dans la première zone, et dans la deuxième un numéro entier attribué à cette rubrique (vous pouvez inscrire ce que vous voulez dans la troisième, par exemple le titre de la rubrique). Avec cette carte, vous pouvez appeler n'importe quelle rubrique depuis Delphi en exécutant le méthode HelpContext de l'objet Application.

Ouverture d'une rubrique de l'aide via TApplication.HelpContext

Application.HelpContext(No_Rubrique_Dans_La_Carte);

Avant d'exécuter un tel code, vous devez avoir défini le fichier d'aide de l'application. Ceci peut être fait soit en conception via la boîte de dialogue Options de l'application, onglet Application, soit à l'exécution via la propriété HelpFile de l'objet Application.

Une utilisation typique est de placer dans l'événement OnClick du menu Aide le code suivant :

Ouverture de l'aide depuis l'événement d'un menu

procedure TForm1.MenuAideClick(Sender: TObject);
begin
Application.HelpContext(1);
end;

De fait, le sommaire recevra en général le numéro 1 dans la carte.

Une autre utilisation est de renseigner la propriété HelpContext d'un contrôle Delphi avec le numéro de la rubrique décrivant ce contrôle. Ainsi, lorsque l'utilisateur appuiera sur F1 alors que le focus est attribué à ce contrôle, affichera automatiquement la rubrique associée.

IV-C-4 - Autres fonctions de Help Workshop

Pour ce qui est des autres fonctions de Help Workshop, vous les exposer dépasse le cadre de ce tutoriel. Reportez-vous à l'aide de ce logiciel.

IV-D - Compilation et premier test

Compilez à nouveau puis ouvrez le fichier d'aide pour le tester. Vous pouvez dès lors appeler votre fichier d'aide depuis votre application Delphi suivant la méthode décrite ci-dessus.

Il nous reste à créer un fichier de table de contenu (Contents file), toujours avec Help Workshop.

V - Création du fichier de sommaire

Cette quatrième étape est optionnelle. Elle permet néanmoins de créer un fichier d'aide complet et facilite la navigation (table de sommaire, index et fonction de recherche automatiques).

V-A - Création du fichier

Lancez Help Workshop. Sélectionnez le menu « File|New ». Dans la boîte de dialogue qui s'affiche, sélectionnez « Help Contents » puis cliquez sur OK. Une nouvelle sous fenêtre s'affiche. C'est la fenêtre d'édition des fichiers de type Table de contenu. Enregistrez tout de suite votre fichier dans le même dossier que le fichier .hpj avec le même nom, mais l'extension .cnt (contents). Nous pouvons maintenant réaliser notre sommaire.

V-B - Réalisation du sommaire

Vous pouvez voir dans la partie gauche de la fenêtre l'aperçu du sommaire. Pour l'instant il est vide. Nous allons donc le réaliser.

Rappelons-nous d'abord la structure de notre fichier d'aide que nous avions réalisée dans la première phase :

Accueil
Sommaire
Utilisation du programme
Nom et prénoms
Surnom
Numéro de téléphone
Date de naissance

C'est exactement ce qui se retrouvera dans la fenêtre de sommaire une fois qu'il sera terminé.

Cliquez donc sur le bouton « Add Below » (ajoute une nouvelle ligne en dessous de la ligne sélectionnée tandis que « Add Above » l'ajoute au-dessus de la ligne sélectionnée ; quand la liste est vide, les deux boutons créent une première ligne). Dans la boîte de dialogue qui apparaît, sélectionnez « Topic » (par défaut), puis entrez « Accueil » dans la zone Title (titre) et « Accueil » également dans la zone Topic ID (identificateur unique de la rubrique). Cliquez sur OK. Vous pouvez observer la première ligne dans la fenêtre d'édition. Faites de même pour la rubrique Sommaire (titre : « Sommaire » ; identificateur : « Sommaire »).

Ajoutons maintenant le sous-titre « Utilisation du programme » qui, je vous le rappelle, ne correspond à aucune rubrique. Cliquez donc à nouveau sur le bouton « Add Below ». Sélectionnez maintenant « Heading » plutôt que « Topic ». Vous pouvez observer que seule la première zone de texte est encore éditable. Entrez-y « Utilisation du programme » puis cliquez sur OK. Remarquez que l'icône pour cette nouvelle ligne n'est pas la même que pour les deux premières.

Ajoutez maintenant la ligne « Nom et prénoms » de la même manière que vous avez ajouté les deux premières lignes. Cette nouvelle ligne s'indente automatiquement de manière à se trouver sous le titre « Utilisation du programme ». Si vous devez indenter manuellement une ligne, cliquez sur le bouton « Move Right » (pour désindenter une ligne, cliquez sur « Move Left »). Faites de même pour les trois dernières rubriques (que vous ne devez normalement pas indenter, car elles le sont automatiquement).

V-C - Réglages supplémentaires

Le sommaire est maintenant terminé. Il reste encore quelques petits réglages à faire.

Dans la zone « Default filename », indiquez le nom de fichier du fichier .hlp correspondant à votre fichier d'aide (ici « DemonstrHLP.hlp »). Dans la zone « Default title », indiquez le titre de votre aide (par exemple « Aide de DemonstrHLP »).

Le fichier de sommaire est maintenant opérationnel. Enregistrez-le et fermez-le (ne quittez pas Help Workshop, il faut encore faire un tout petit réglage dans le fichier .hpj).

Rouvrez donc le fichier .hpj. Cliquez sur le bouton « Options ». Dans la boîte de dialogue qui s'affiche, prenez l'onglet « Files ». Cliquez sur le bouton « Browse » à côté de la zone « Contents file » puis sélectionnez le fichier de sommaire que vous venez de terminer. Validez puis, dans la fenêtre principale, cliquez sur « Save and Compile » pour recompiler le fichier d'aide.

V-D - Le fichier d'aide est complètement terminé

Votre fichier d'aide est maintenant complètement terminé. Il ne vous reste plus qu'à le tester.

VI - Tester le fichier d'aide

Il ne reste plus qu'à tester le fichier d'aide, c'est-à-dire tester tous les liens, le sommaire, l'index, la fonction de recherche, et toutes les autres choses.

VII - Fin de ce tutoriel

VII-A - Clôture du tutoriel

Nous voici arrivés au terme de ce tutoriel. Vous pouvez ici télécharger le zip contenant les sources du programme et du fichier d'aide d'exemple.

J'espère que ce tutoriel vous aura bien expliqué comment utiliser Help Workshop et comment créer un fichier d'aide.

VII-B - Liens

Vous pouvez également consulter l'article de Gilles Louise :
https://glouise.developpez.com/cbconseils/cbconseils2.php#L31

VII-C - Remerciements

Un grand merci à Laurent Dardenne pour la correction orthographique et de mise en forme.

(1)Rubrique pop up : rubrique se situant dans une petite fenêtre qui apparaît au-dessus de toutes les autres