Fabriquer un fichier CHM - HTML Help - Jurixt Offline (making of)

Révision 1.1
Mise à jour : 5 juillet 2002

HTML compilé (jurixt.com)

Introduction

Depuis mars 1999, une bonne partie du site Jurixt.com est donc disponible sous la forme d'un fichier d'aide au format HTML compilé (MS HTML Help). Par commodité de langage, on appelle ça "HTMLHelp" par opposition aux fichiers "Winhelp". Ces derniers, largement répandus dans les vieilles versions de Windows. Outre le fait que le premier affiche un contenu formaté au format HTML et l'autre non, la principale différence entre ces deux systèmes d'aide, celle qui saute immédiatement aux yeux, c'est la possibilité d'afficher deux fenêtres simultanées, l'une contenant la table des matière, l'autre les sujets, ces deux fenêtres pouvant se synchroniser. Quant au format Winhelp, il s'appuie sur des fichiers *.RTF et ne permet d'afficher qu'une fenêtre : la navigation en est rendue d'autant plus malaisée. En plus de ces deux formats, on peut citer WebHelp et JavaHelp.

L'aide au format CHM est omniprésente sous Windows 2000 et XP, encore que le format particulier de Windows XP s'appuie sur une version dont le kit de développement n'est pas encore rendu public (CHM version 2).

Un fichier HTMLHelp porte l'extension *.CHM. Techniquement, un fichier CHM n'est rien d'autre qu'un ensemble de fichiers HTML qui sont regroupés et compressés sous un seul fichier. Les textes, les images, les sons, les animations, etc., tout ou presque peut être compilé dans un fichier CHM. Et un fichier CHM peut à son tout être incorporé dans une page HTML pour être visible online.

Le but de cette page se limite à expliquer en quelques mots comment je réalise mes fichiers d'aide CHM pour les seuls besoins de mon site. Plus loin, j'indiquerai les liens vers des sites et des outils pour ceux qui veulent pousser plus loin la réalisation et l'utilisation de ces fichiers.
Les outils

Il existe bien évidemment un nombre important d'outils commerciaux pour fabriquer de tels fichiers dont une liste sera donnée plus bas. L'important pour moi c'est de livrer le seul outil gratuit permettant de faire à peu près tout ce que l'on veut avec des CHM. Il s'agit de HTML Workshop 1.31. Ce logiciel qui n'est pas nouveau remplit parfaitement son office.

Pour disposer de l'ensemble de la documentation et des outils de HTML Workshop, vous devez vous rendre sur cette page et télécharger tous les composants listés. Ces outils n'existent qu'en anglais.

Voici la liste des différents composants disponibles sur la page de téléchargement de Microsoft et les commentaires relatifs à ces éléments :
Nom | Commentaires
HelpDocs.ZIP - 1,382 Kb | Ensemble de fichiers CHM composant la documentation d'ensemble : Le guide général pour créer des CHM (Htmlhelp.chm) Les références du contrôle ActiveX (Hhaxref.chm) Les références de l'API (Api.chm) Les références des tags HTML (Htmlref.chm) L'aide du viewer HTML Help (Viewhlp.chm) La librairie de l'API (Htmlhelp.lib)
hhupd.exe - 734 Kb | Jeu de mise à jour des contrôles CHM. Ne pas installer sous Windows 2000 ou XP.
htmlhelp.exe - 3,508 Kb | HTML Workshop + fichiers d'aide.
htmlhelpj.exe - 1,446 Kb | version japonaise
Pour les machines NT et 9x, l'installation de HHUPD.EXE permettra de s'assurer de disposer des contrôles à jour. Pour Windows 2000/XP, seul HTMLHELP.EXE devrait être téléchargé.
Utilisation basique

HTML Workshop Au lancement de HTML Workshop, vous pouvez lancer l'assistant de création de projet qui va vous guider pour les principales étapes de création d'un CHM. Vous lui indiquez l'emplacement de votre projet (n'importe quel dossier), le fait que vous possédiez ou pas des fichiers HTML à intégrer, etc. Nous partons de l'hypothèse où vous avez déjà un ensemble de pages HTML à compiler. Leur emplacement n'a pas d'importance de sorte que vous n'avez pas à les dupliquer pour les placer dans le même dossier que votre fichier de projet. Lors de la sélection des fichiers HTML à intégrer, vous pouvez sélectionner plusieurs fichiers d'un coup. Le fichier de projet, celui qui contient toutes les descriptions de votre futur CHM porte l'extension HHP. Ce fichier est facilement éditable avec n'importe quel éditeur de texte comme le bloc-notes. Voici à quoi peut ressembler sa structure.

Structure du fichier HHP

[OPTIONS]
Compatibility=1.1 or later
Compiled file=jan2002.chm
Contents file=Table_win98.hhc
Default Font=Tahoma,8,0
Default Window=xt
Default topic=intro.html
Display compile progress=Yes
Full-text search=Yes
Language=0x40c Français (France)
Title=Introduction

[WINDOWS]
xt="Jurixt.com [version offline], éd. Janvier 2002 (c) Xavier TOUBHANS - xavier@jurixt.com","Table_win98.hhc",,"intro.html",,,,,,0x63520,,0x3006,[3,0,1017,721],,,,,,,0

[FILES]
intro.html
io_sys.htm
win98.htm
auteur.htm
systeme.html
communication.html
installation.html
notions.html
95-98.html
oe-html-1.htm
oe-html-2.htm
oe-html-3.htm
etc.
[INFOTYPES]

En quelque sorte, ces informations contiennent l'essentiel de ce que doit savoir HTML Workshop pour compiler votre fichier CHM : le nom final du fichier CHM à générer, le nom du fichier de la table des matière, le nom de la police par défaut, le nom éventuel des paramètres de la fenêtre personnalisée si vous décidez d'en créer une, etc. Toutes ces informations sont directement saisissables via l'interface graphique de HTML Workshop.

Exemple :

Imaginons un site composé de trois pages, index1, index2 et index3. Les graphiques composant ces pages sont situés dans un sous-dossier "IMG". La feuille de style de ces trois pages est située dans un sous-dossier "CSS". A ce stade, seuls les trois fichiers HTML seront utilisés, nous verrons plus bas comment intégrer de nouveaux fichiers à un projet CHM existant.

Créez un dossier où vous placez tous ces fichiers. Lancez HMTL Workshop, choisissez de créer un nouveau projet, indiquez l'endroit où le fichier du projet (extension HHP) sera stocké, cochez ensuite la case comme quoi vous possédez déjà des fichiers HTML à intégrer au projet, sélectionnez le ou les fichiers en question dans la boîte de dialogue suivante et validez. Vous vous retrouvez alors avec l'interface ci-contre.
A la ligne "default topic=index1.htm" on remarque que la page par défaut sur laquelle s'ouvrira le fichier CHM est index1.htm. Bien entendu, cet ordre peut être modifié à loisir depuis l'interface graphique de HTML Workshop.

Il convient maintenant de créer une table des matières. Cette table s'affichera dans le panneau de gauche du fichier CHM et en cliquant sur l'un de ses titres, le contenu de la page appelée s'affichera dans le panneau de droite, tout comme n'importe quelle page HTML composée de frames ("cadres"). Pour cela, appuyez sur l'onglet "Contents", HTML Workshop vous demande alors si vous souhaitez créer un nouveau fichier ou prendre un fichier préexistant. Par définition, vous créez un nouveau fichier (extension HHC) que vous enregistrez dans votre répertoire de travail.

Sur cet onglet, de nouvelles icônes apparaissent dans le menu vertical de gauche. En cliquant sur l'icône symbolisant un dossier, vous insérez une rubrique sous laquelle vous pouvez alors insérer des sous-rubriques ou des pages. A vous de voir selon vos besoins. Dans notre exemple, nous créons une rubrique renvoyant à la page index1, puis un sous-titre renvoyant à la page index2 et enfin une page seule, de même niveau hiérarchique que la rubrique, renvoyant à index3.
Sachez aussi que vous pouvez directement modifier le code HTML d'une page en double cliquant sur son nom.

Il y a de fortes chances pour que lors de l'édition de la page 3 celle-ci se retrouve au même niveau hiérarchique que la page2. Pour la faire remonter d'un niveau, il suffit de cliquer sur les flèches de direction symbolisées dans la palette d'outils verticale.
Si vous appuyez sur le bouton "Edit" pour modifier les renseignements relatifs à une rubrique ou une page, vous avez également accès à un onglet "Advanced" qui vous permet notamment de définir la fenêtre cible (mais laissez le champ libre pour le moment sauf pour une utilisation avancée avec des fenêtres multiples) mais aussi d'associer une icône particulière au titre en question (42 icônes disponibles).

La partie la plus fastidieuse pour la création des rubriques et des pages ou sous-rubriques, c'est d'avoir à chaque fois à nommer ces éléments (le titre qui apparaîtra dans la table des matières). HTML Workshop n'est pas capable de récupérer le titre d'une page HTML pour définir le titre de la table des matière : il faut saisir à chaque fois ce titre.

L'autre partie qui peut requérir beaucoup de patience est la création d'un index. Cela n'a rien d'obligatoire, tout dépend du contenu de votre fichier CHM. Mais s'il s'agit de distribuer une aide exhaustive, il faut avouer que c'est un plus pour l'utilisateur. Vous cliquez alors sur le troisième onglet "Index", on vous propose alors de créer un nouvel index. Ici, vous insérez un nouveau mot en cliquant sur l'icône représentant une clef et, dans la boîte de dialogue, vous associez à ce mot autant de pages auxquelles ce mot peut faire référence. Lorsque l'utilisateur cliquera sur l'index, il aura un choix de "destinations", un mot-clef renvoyant à plusieurs pages. Là encore, les mots peuvent être présentés sous forme de rubriques et sous-rubriques de la même façon que la table des matières.

Dans chacun des onglets "Project", "Contents" et "Index", la première icône vous permet de définir des paramètres généraux pour personnaliser ces catégories d'éléments. Il s'agit notamment de choisir la typo, la couleur des fonds de fenêtre, éventuellement la frame par défaut, etc.

Lorsque tout est en place et que vos pages sont toutes référencées dans votre projet, il vous reste encore à peaufiner les paramètres généraux de l'interface du fichier CHM qui va être créé.

En retournant au premier onglet "Project" puis en cliquant sur l'icône "Add/Modify Windows definitions" vous pourrez modifier sensiblement la façon dont se présentera le fichier compilé : masquage ou affichage de boutons, dimensions de la fenêtre, titre dans la barre de titre, présence ou non des onglets "Favoris", "Rechercher", "Index", synchronisation automatique ou non des rubriques avec le contenu, etc.

Toutes ces opérations étant effectuées, il ne vous reste plus alors qu'à compiler votre projet pour générer un fichier CHM conforme à vos voeux. Un fichier log est généré dont les messages d'erreurs s'affichent dans la fenêtre de HTML Workshop afin que vous puissiez corriger les fautes éventuelles.

Si vous souhaitez ajouter ou supprimer ultérieurement des fichiers HTML dans votre projet, il vous suffit de relancer HTML Workshop et de cliquer sur le bouton "Add/Remove Topic Files". Vous cliquez sur le bouton "Add" et vous sélectionnez dans notre exemple index4.htm cité plus haut. Le nouveau fichier apparaîtra dans la section [FILES] et il vous faudra ensuite définir sa place dans votre table des matières en cliquant sur l'onglet "Contents" et en suivant la procédure décrite plus haut pour la définition des rubriques et sous-rubriques.

Considérations Diverses

Faites attention aux liens internes de vos fichiers HTML. Si vous copiez la structure d'un site, reproduisez fidèlement son arborescence.
HTML Help Workshop est un compilateur de fichiers CHM, mais c'est aussi un décompilateur. Ouvrez donc les autres fichiers CHM disponibles sur votre PC pour vous familiariser avec les fichiers plus complexes.
Bien que de nombreux types de fichiers peuvent être encapsulés dans un fichier CHM, un certain nombre d'entre eux requièrent un lien externe. C'est le cas des fichiers son par exemple. Une page HTML avec un fond sonore ne fonctionnera une fois compilée que si le fichier son est externe au fichier CHM (et de préférence dans le même répertoire racine). Idem pour les applets Java. Pour des exemples sur la façon de remédier au problème, consultez ce site : .
Si vous avez IE 5.5 SP1, un bug du correctif de sécurité empêche les liens internes vers des fichiers ZIP et PDF. Passez au SP2 ou à IE 6.x.
Faites attention à la syntaxe de vos pages HTML lorsqu'elle contiennent des scripts. Si vous utilisez par exemple des pages HTML incluses dans des frames et qui contiennent un script qui impose les frames parents, le résultat dans un fichier CHM provoquera une erreur.
Erreur de registration : lors de la compilation de votre fichier CHM, si vous remarquez cette erreur en tête du fichier log : "HHC6003: Error: The file Itircl.dll has not been registered correctly", alors faites une recherche dans votre disque dur sur la DLL "itcc.dll". Si vous la trouvez, vérifiez qu'elle se trouve dans \Windows\System ou copiez-là dans ce dossier puis exécutez alors la commande suivante :
"regsvr32 c:\windows\system\itcc.dll"
Les fichiers CHM compressent les fichiers HTML qu'ils recèlent. Inutile de compresser à son tour un fichier CHM, le gain serait très négligeable.
Même s'il s'agit à la base de fichiers HTML, un fichier CHM ne s'incorpore pas dans une page Web directement. Il faut pour cela utiliser un contrôle ActiveX (se référer à l'aide en ligne de HTML Workshop).

Liens

A ma connaissance il n'existe pas de ressources françaises sur ce thème. Il faudra donc se "contenter" des sites en langue anglaise :

Helpware : excellente ressource disposant d'une FAQ, d'outils et de nombreuses mises à jour. On ira en particulier sur cette page pour consulter des infos très techniques sur la base de registre et les différents paramètres relatifs aux fichiers CHM sur toutes les plates-formes Windows.
Rick Tips : là vous pourrez télécharger les astuces et conseils de ce développeur dans un format CHM qui vous en dira long sur les possibilités offertes par ce format.
World Wide WInnovations : vous fournira des informations utiles ainsi que des outils gratuits parmi lesquels un vérificateur de DLL et OCX afin de savoir si votre PC dispose des contrôles adéquats.
Helpmaster : site allemand en langue anglaise qui constitue l'une des plus grandes ressources sur le sujet.
HTML Help Center : tout ce qui tourne autour du sujet y est traité. Les développeurs sont principalement visés.
Newsgroups : abonnez-vous au forum microsoft.public.helpauthoring

Softs similaires

En dehors de HMTL Workshop, qui reste un outil largement suffisant pour des besoins rudimentaires, de nombreux éditeurs proposent des outils bien plus puissants, destinés à la production de gros fichiers d'aide (Windows Help, MS HTML Help, Web Help, Java Help, etc.) pourvus de capacités interactives et/ou collaboratives (recueillir les avis des utilisateurs par exemple et les traiter), capables de convertir tous types de documents en projets d'aide, etc.

Ehelp : éditeur du logiciel RoboHelp qui se décline en de multiples versions plus ou moins puissantes. Rien à dire sur ces sots, ils sont capables de tout faire et sont d'une interface très agréable. Mais vérifiez tout de même si le soft gratuit de Microsoft exige réellement que vous dépensiez au minimum $500 pour des fonctions supplémentaires !

FAR : constamment mis à jour, ce logiciel de moins de $ 50 est très puissant. Initialement, il a été conçu pour transformer des sites Webs FrontPage en fichiers CHM. Il est capable de transformer un CHM pour une publication sur le Web. Pour son prix, il est réellement très complet.

Windows Help Designer : pour un coût situé entre les deux logiciels cités plus haut, WHD offre lui aussi des fonctions très complètes en matière d'édition de fichiers d'aide. L'un de ses versions permet également de convertir au format PDF.
Les différents formats d'Aide
 | WebHelp | MS HTML Help | WinHelp | Oracle Help | JavaHelp
Navigateur requis | IE, Netscape, etc. | IE 4 et + | Aucun | Intégré | Aucun
Plate-forme | Toutes | 9x, NT4, 2000, XP. | Windows | Toutes | Toutes
Runtime requis | Aucun | Aucun si IE4 et + | Aucun | JRE 1.21 + Oracle Help | JRE 1.21 + Java Help 1.0
Extension | Mixtes | .CHM | .HLP et .CNT | .HS + .JAR | .HS + .JAR
Compression | oui en partie | oui | oui | oui | oui
Tableau complet au format PDF emprunté au site de eHelp