HTML Help

Cette page est consultable pour des raisons historiques.

Présentation

HTMLHelp est le format standard d'aide pour les applications Windows. Il remplace le format WinHelp.

La principale différence entre ces deux formats est le format des documents qui composent l'aide. HTMLHelp utilise des fichiers HTML alors que WinHelp utilise des fichiers RTF.

Des informations complémentaires peuvent être consultées sur le site MSDN de Microsoft :

http://msdn.microsoft.com/fr-fr/library/windows/desktop/ms670068%28v=vs.85%29.aspx

La version de HTML Help Workshop de cet article est la 1.3 :

HTMLHelp utilise comme WinHelp plusieurs types de fichiers :

Extension	Type de fichier
.HHP	Le projet
.HHC	La table des matières
.HHK	L'index
.CHM	Le fichier d'aide compilé
.HTM	Un fichier html qui compose l'aide
.H	Un fichier d'en tête

Microsoft propose un outils "HTML Help Workshop" pour concevoir des aides au format HTMLHelp. Pour l'utiliser, il faut le downloader à l'url http://msdn.microsoft.com/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp et l'installer.

Pour lancer l'outils HTML Help Workshop, il suffit de cliquer sur l'option "HTML Help Workshop" dans le menu "Démarrer / Programmes / HTML Help Workshop".

Par défaut, l'outils s'ouvre avec un projet vide.

La création d'un projet HTMLHelp

Pour créer un nouveau projet, il faut utiliser l'option "New" du menu "Fichier".

Sélectionner "Project" et cliquer sur "Ok" pour afficher l'assistant de création de projet :

L'assistant propose de convertir un ancien projet au format winHelp : dans ce cas, cocher la case correspondante.

Cliquer sur "Suivant".

Saisir ou sélectionner le nom du projet sous la forme d'un nom de fichier.

Il peut être pratique, avant de créer le projet, de créer certains des fichiers HTML qui composeront l'aide. Ceux ci pourront être automatiquement intégrés dans le projet à sa création. Dans ce cas, il faut cocher les types de fichiers qui seront intégrés à la création du projet.

Cliquer sur "Terminer".

L'assistant créé un nouveau projet.

Remarque : il peut être pratique de créer dans le répertoire qui va contenir les sources de l'aide, un répertoire nommé html qui contiendra les fichiers html qui composent l'aide.

Les paramètres du projet sont sauvegardés dans un fichier ayant pour extension .hhp. Ce fichier est un fichier texte composé de plusieurs sections dont certaines sont optionnelles (elles dépendent des options sélectionnées) :

OPTIONS : options générales du projet
WINDOWS : options des fenêtres du projet
FILES : liste des fichiers contenus dans le projet
ALIAS : association des ID avec un fichier (utilisé pour réaliser une aide contextuelle dans une application)
MAP : association de valeurs aux ID
TEXT POPUP : texte pour l'aide de type "qu'est ce que c'est"


[OPTIONS]
Compatibility=1.1 or later
Compiled file=testhtmlhelp.chm
Contents file=Table of Contents.hhc
Display compile progress=No
Full-text search=Yes
Index file=Index.hhk
Language=0x40c Fran?ais (France)
[FILES]
html\aide4.htm
html\aide2.htm
html\aide3.htm
html\aide1.html

L'outils Workshop

La fenêtre principale de cette outils est composée d'une barre de menu, d'une barre d'outils et d'une partie centrale séparée en deux parties.

La partie de gauche est composé de trois onglets. Chaque onglet possède une barre d'outils dépendant de celui qui est sélectionné.

L'onglet "Project" permet de modifier les caractéristiques du projet (options, configuration de la fenêtre, gestion des fichiers qui composent l'aide, etc ...).

L'onglet "Contents" permet de créer et gérer la table des matières de l'aide.

L'onglet "Index" permet de créer et gérer l'index de l'aide.

La barre d'outils

HTML Help Workshop possède une barre d'outils avec les actions suivantes :

Icônes	Rôle
	Créer une nouvelle entité
	Ouvrir un projet
	Lancer la compilation
	Permet d'afficher un fichier d'aide généré
	Aide en ligne

La barre d'outils de l'onglet Project

L'onglet "Project" possède une barre d'outils verticale avec les options suivantes :

Icones	Rôle
	Modifier les options du projet
	Ajouter ou supprimer un fichier html au projet
	Ajouter ou modifier l'aspect de la fenêtre d'aide
	Permet d'associer des ID à chaque sujet pour réaliser une aide contextuelle pour l'application utilisant l'aide
	Voir le source html d'un fichier inclus au projet
	Sauvegarder tous les fichiers du projet
	Sauvegarder tous les fichiers et compiler le projet

Les options du projet

Il est possible de préciser les options du projet en cliquant sur l'icône de l'onglet "Project".

Il est possible de préciser un titre, le fichier HTML qui sera affiché par défaut et la fenêtre par défaut.

L'onglet "Files" permet de préciser certains fichiers utilisés par le projet.

L'onglet "Compiler" permet de préciser certaines options pour la compilation.

Remarque : l'option "Compile full-text search information" doit être activée si l'onglet de recherche dans l'aide est activé (Voir les options de fenêtre).

Les fichiers HTML

Les pages qui composent l'aide sont au format HTML. Ces fichiers peuvent être créés avec n'importe quel outils permettant leur conception.

Le plus simple est de rassembler ces fichiers dans un répertoire nommé html à la racine du projet d'aide. Ce répertoire doit également contenir directement ou dans sa sous arboresence tous les fichiers nécessaires aux pages HTML (images, feuilles de styles, etc...).

Ajout d'un fichier HTML existant

Pour ajouter un fichier HTML au projet, il suffit de cliquer sur l'icône dans l'onglet "Project".

Il suffit de cliquer sur "Add" et de sélectionner le fichier à ajouter. Dans la boîte de sélection du fichier, il est possible de sélectionner plusieurs fichiers en maintenant la touche "Ctrl" enfoncée et en cliquant sur les fichiers concernés.

Un fois le ou les fichiers ajoutés, il suffit de cliquer sur "OK".

Les fichiers sont ajoutés dans la liste des paramètres du projet.

Création d'un nouveau fichier HTML avec Workshop

Pour créer un nouveau fichier HTML, il suffit de cliquer sur l'icône ou de sélectionner l'option "New" du menu "File".

Il faut sélectionner "HTML File" et cliquer sur "OK".

Il faut saisir le titre du fichier HTML et cliquer sur "Ok".

La partie droite du logiciel contient alors le source HTML du nouveau fichier :

Il faut saisir le code HTML. Pour enregistrer le fichier, il faut sélectionner l'option "Save as" du menu "File" ou cliquer sur l'icône de la barre de menu.

Il faut ensuite ajouter le fichier au projet comme indiqué dans la section précédente.

La table des matières

L'aide peut contenir une table des matières personnalisée. La table des matières est un élément hiérarchique qui permet d'organiser les différents fichiers HTML qui composent l'aide et ainsi facilite la navigation dans l'aide.

Ajouter une table des matières

Pour ajouter une table des matières, il suffit de cliquer sur l'onglet "Contents".

Une boîte de dialogue s'ouvre pour demander de créer un nouveau fichier pour la table des matières ou d'utiliser un fichier existant.

Cette boite de dialogue ne s'affiche que si aucun fichier de table des matières n'est associé au projet.

Laisser l'option "Create a new contents file" sélectionnée et cliquer sur "Ok". Il faut saisir un nom pour permettre la sauvegarde du nouveau fichier créé.

L'onglet Content

Cet onglet permet de modifier le contenu de la table des matières.

Cet onglet dispose d'une barre d'outils verticale avec les options suivantes :

Icône	Rôle
	Modifier les propriétés de la table des matières
	Ajouter un titre
	Ajouter une page HTML
	Modifier l'élément sélectionné
	Supprimer l'élément courant
	Décaler l'élément courant vers le haut
	Décaler l'élément courant vers le bas
	Décaler l'élément courant vers la droite
	Décaler l'élément courant vers la gauche
	Voir le source du fichier HTML sélectionné
	Enregistrer le fichier de la table des matières

Ajouter un titre

Pour ajouter un titre, il suffit de cliquer sur l'icône . Une boite de dialogue permet de saisir les caractéristiques du titre.

Il suffit de saisir le titre dans la zone "Entry Title" et de cliquer sur "Ok".

Ajouter un sujet

Un sujet est un titre associé à un fichier HTML. Pour ajouter un sujet, il suffit de cliquer sur l'icône . Une boite de dialogue permet de saisir les caractéristiques :

Il faut saisir le titre dans la zone "Entry title" et de cliquer sur le bouton "add". Une boite de dialogue permet d'associer cette entrée de la table des matières avec un fichier HTML.

Cliquer sur "Browse" et sélectionner le fichier correspondant. Cliquer sur "Ok" pour fermer la boîte de dialogue.

Cliquer sur "OK" pour fermer la boite de dialogue.

L'onglet "Contents" est mis à jour pour refletter les modifications :

Modifier un élément

Il suffit de sélectionner l'élément et de cliquer sur l'icône . Une boite de dialogue avec deux onglets s'ouvre :

L'onglet "Advanced" permet modifier les paramètres avancés :

Il est notamment possible de modifier l'icône de l'élément en sélectionnant l'icône dans "Image Index".

Les propriétés de la table des matières

Pour modifier les propriétés de la table des matières, il suffit de cliquer sur l'icône . Une boite de dialogue s'ouvre pour permettre la modification des propriétés. Elle contient 3 onglets.

L'onglet General

La case à cocher "Use folder instead of books" permet de sélectionner le type d'icône utilisé devant chaque entrée de la table des matières :

répertoire : si la case est cochée
livre : si la case est décochée

Ceci ne modifie que l'icône par défaut : il est possible de modifier cet icône ultérieurement.

Il est possible en cochant l'autre case à cocher de préciser ses propres icones.

Modifier la structure de la table de matière

Les quatre boutons ci dessous permettent de modifier la position de l'élément sélectionné dans l'arborescence de la table des matières.

L'index

L'index est une liste de mot clés qui sont associés à un ou plusieurs fichiers HTML.

Création d'un index

Si aucun index n'est associé au projet, un clic sur l'onglet "Index" ouvre une boite de dialogue qui demande la création d'un nouveau fichier d'index ou l'association avec un fichier existant.

Laisser l'option "Create a new index file" sélectionné et cliquer sur "OK".

Saisir un nom pour le nouveau fichier et cliquer sur "Ok".

L'onglet Index

Cet onglet permet de modifier l'index. Il dispose d'une barre d'outils verticale avec les options suivantes :

Icône	Rôle
	Modifier les propriétés de la table des matières notamment la police utilisée
	Ajouter un mot clé
	Modifier l'élément sélectionné
	Supprimer l'élément courant
	Décaler l'élément courant vers le haut
	Décaler l'élément courant vers le bas
	Décaler l'élément courant vers la droite
	Décaler l'élément courant vers la gauche
	Voir le source du fichier HTML sélectionné
	Trier les mot clé dans l'ordre alphabétique
	Enregistrer le fichier de l'index

Ajouter un mot clé

Pour ajouter un mot clé, il suffit de cliquer sur l'icône . Une boite de dialogue permet de saisir les caractéristiques du nouveau mot clé :

Il faut saisir le mot clé dans la zone "Keyword" puis cliquer sur le bouton "Add" pour lui associer un ou plusieurs fichiers avec la boîte de dialogue qui s'ouvre.

Il faut sélectionner le fichier HTML et cliquer sur "Ok".

Il est possible d'associer plusieurs fichiers à un même mot clé en répétant l'opération d'ajout d'un fichier.

Les fenêtres d'affichage de l'aide

Le bouton permet de définir ou de modifier l'aspect de la fenêtre dans laquelle l'aide va s'afficher.

Lors du clic sur le bouton, si aucun type de fenêtre n'est définie, HTML Help Workshop propose de définir un nouveau type de fenêtre :

Il suffit de saisir un nom et cliquer sur "OK".

Les differents onglets permettent de modifier l'apparence de ce type de fenêtre.

L'onglet "General" permet d'ajouter ou de supprimer un type de fenêtre et pour le type sélectionné de préciser le titre de la fenêtre.

L'onglet "Boutons" permet de préciser les boutons qui seront affichés dans la barre d'outils de la fenêtre.

Les boutons ont un rôle similaire à ceux d'Internet Explorer puisque c'est lui qui est utilisé par HTMLHelp.

Voici par exemple un aperçu de l'aide avec les options précisées ci dessus :

L'onglet "Position" permet définir la position d'affichage et la taille de la fenêtre pour le type de fenêtre sélectionné.

Il est possible de saisir directement les coordonnées et la taille de la fenêtre. Le bouton "Default position" permet d'initialiser les coordonnées et la taille avec une valeur par défaut. Le bouton "Autosizer" ouvre une fenêtre que l'on déplace et redimensionne pour facilement définir les coordonnées et la taille. Celles-ci correspondront aux coordonnées et à la taille de la fenêtre au moment du clic sur le bouton "Ok".

L'onglet "Files" permet de préciser certains fichiers utilisés par le projet.

Plusieurs données peuvent être renseignées pour la fenêtre sélectionnée :

TOC : le fichier .HHC contenant la table des matières
Index : le fichier .HHK contenant l'index des mot clés
Default : fichier affiché par défaut lors de l'ouverture de l'aide
Home, Jump 1 , Jump 2 : le fichier affiché lors du clic sur le bouton correspondant

L'onglet "Navigation pane" permet de préciser les options pour le panneau de navigation à gauche de l'aide.

Cet onglet permet de préciser quels onglets seront affichés dans le panneaux et quel sera celui affiché par défaut.

La case à cocher "Auto sync" permet de synchroniser automatiquement la page affichée avec la rubrique sélectionnée dans le panneau.

La case à cocher "Search tab" permet d'ajouter un onglet "Rechercher" dans le panneau pour permettre à l'utilisateur de faire des recherches dans toute l'aide.

Le mapping entre les rubriques et les ID

Le bouton permet d'ouvrir une boîte de dialogue "HTMLHelp API Information" pour faire la correspondance entre des identifiants (ID) et les rubriques de l'aide.

Le premier onglet permet d'associer un ou plusieurs fichiers particuliers au projet. Ces fichiers contiennent la définition de chaque ID ainsi que la valeur qui leur est associée.

Le contenu de ces fichiers doit avoir un formattage particulier : la commande #define suivie d'un espace suivie du nom de l'ID suivie d'un ou plusieurs blancs suivi de sa valeur.

Chaque nom d'ID et chaque valeur sont libres mais doivent être tous différents pour un même projet. Le standard est de préfixer le nom de l'ID par IDH_.

Pour associer un fichier au projet, il suffit de cliquer sur le bouton "Header file ..." et de sélectionner le fichier en cliquant sur le bouton "Browse".

Un clic sur "Ok" ajoute le fichier.

L'onglet "Alias" permet d'associer à chaque ID, une rubrique de l'aide.

Un clic sur "Add" permet d'ouvrir une boite de dialogue pour réaliser une nouvelle association :

Il suffit de saisir l'ID et de sélectionner un des fichiers qui compose l'aide.

Un clic sur "OK" ajoute cette nouvelle association.

Il faut répéter cette opération pour chaque ID.

Tout ceci permet de réaliser une aide contextuelle dans l'application qui utilise l'aide. Plusieurs outils de développement de type RAD (Delphi ou Visual Basic par exemple) définissent une propriété particulière pour les fenêtres dans laquelle il suffit de préciser la valeur de l'ID. Une fois l'association du fichier d'aide affectuée à l'application avec l'outils de développement, il suffit à l'utilisateur d'appuyer sur F1 pour obtenir l'aide sur la rubrique associée à l'ID de la fenêtre.