Construisez et appelez aisément vos manuels utilisateur avec JavaHelp

Hugo ETIEVANT

Construisez et appelez aisément vos manuels utilisateur avec JavaHelp

Télécharger l'outil JavaHelp 2.0.01

Télécharger les sources de mes exemples

- Titre : Construisez et appelez aisément vos manuels utilisateur avec JavaHelp

- Auteur : Hugo ETIEVANT

- Parution : 23 mai 2004

- Licence : Copyright ® 2004 Hugo ETIEVANT. 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. Introduction

- II. Autres solutions

- III. Fonctionnalités principales

- IV. Atouts

- V. Déploiement

- VI. Navigateur JavaHelp

- VII. Création du manuel

- VIII. Visualisation du manuel

- IX. Écriture du contenu du manuel

- X. Exemple de fichier HTML

- XI. Le fichier HelpSet

- XII. Exemple de fichier HelpSet

- XIII. La carte de correspondances

- XIV. Exemple de carte de correspondances

- XV. La table des matières

- XVI. Exemple de table des matières

- XVII. L'index

- XVIII. Exemple d'index

- XIX. Visualisation du manuel

- XX. Archivage du manuel

- XXI. Rendu final

- XXII. Création du moteur de recherche

- XXIII. Test de la base de recherche

- XXIV. Ajout de JavaHelp à votre application

- XXV. Outils connexes

- XXVI. Historique

- XXVII. Note et remerciement du gabarisateur

I - Introduction

L'API JavaHelp permet de construire aisément une documentation pour l'utilisateur final.

Site officiel : http://java.sun.com/products/javahelp/

Téléchargez JavaHelp sur le site officiel.

Ce document a pour but de présenter cette API, vous apprendre à l'utiliser pour construire un manuel et l'utiliser dans vos applications Java.

II - Autres solutions

La construction d'un manuel utilisateur est une étape obligée de tout projet de développement logiciel.

Plusieurs techniques sont possibles :

- un format HTML ou PDF mais avec une navigation limitée ;

- un système applicatif personnalisé, très coûteux à mettre en place ;

- réutiliser un système tierce partie, moins cher avec un temps de développement nul.

JavaHelp appartient à la 3e catégorie et a l'avantage d'être gratuit.

III - Fonctionnalités principales

- Aide à la navigation avec une table des matières, des index et une recherche en « full text ».

- Compression des données et encapsulation dans une archive JAR.

- Extensibilité et personnalisation : l'API JavaHelp peut être dérivée et ses fonctionnalités étendues (IHM, recherche, etc.).

- Sensibilité au contexte (grâce à Swing notamment). La fusion de plusieurs manuels est possible.

- Mise à jour automatique d'un manuel en ligne.

- Adaptabilité de l'interface utilisateur.

- Internationalisation du contenu (I18N).

IV - Atouts

- Il est écrit en Java, il est donc portable sur toute plateforme.

- Il peut être utilisé par des applications non Java.

V - Déploiement

JavaHelp peut être déployé selon plusieurs scénarios :

- en local, embarqué avec l'application qui va l'appeler. Le visualisateur JavaHelp peut être lancé dans un processus distinct de l'application ;

- en réseau, le visualisateur peut appeler des manuels distants. Cela permet d'avoir une seule source cohérente d'informations dont les mises à jour sont répercutées immédiatement ;

- une Applet peut appeler le visualisateur JavaHelpet, présenter le manuel dans un navigateur web ;

- JavaHelp peut être intégré à un serveur d'applications et utiliser son visualisateur en tant que GUI distant.

VI - Navigateur JavaHelp

Voici l'aspect du visualisateur de JavaHelp :

VII - Création du manuel

Le helpset consiste en les métadonnées ainsi que les fichiers de votre manuel.

En voici les étapes de création :

- créer les fichiers HTML contenant les sujets du manuel ;

- créer le fichier helpset (hs) ;

- créer la carte de correspondances (map) ;

- créer la table des matières (toc) ;

- créer le fichier d'index (index) * ;

- créer la base de données pour la recherche sur mot-clé * ;

- compresser et encapsuler tout ceci dans un fichier JAR à distribuer.

Les étapes 5 et 6 sont facultatives, utiles seulement si vous souhaitez intégrer à votre manuel une fonctionnalité de recherche par mot-clé dans le texte.

VIII - Visualisation du manuel

Pour visualiser le manuel généré, il suffit de passer le fichier helpset généré au visualisateur JavaHelp.

Exemple :

set $JAVAHELP_HOME = "c:\jh2.0\";
set $MANUEL_HOME = "c:\myHelp\";
java -jar $JAVAHELP_HOME\demos\bin\hsviewer.jar -helpset $MANUEL_HOME\monHelpSet.hs

IX - Écriture du contenu du manuel

Un préalable à la génération de votre manuel au format JavaHelp, il faut en écrire le contenu dans des fichiers HTML. Ces fichiers seront parsés par le moteur du JRE indépendant de JavaHelp.

Les fichiers HTML doivent respecter les normes HTML 3.2 et CSS1.

X - Exemple de fichier HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>Préface de l'aide</TITLE>
</HEAD>
<BODY>
<H1>Ma première aide en ligne</H1>
<hr><p>Une petite introduction&#8230;</p><hr>
<ul>
<li><a href="profiles.html">Gestion de nos profils</a></li>
<li><ahref="perfs.html">Nos performances</a></li>
<li><ahref="ihm.html">Ergonomie</a></li>
</ul>
</BODY>
</HTML>

XI - Le fichier HelpSet

Le fichier HelpSet généré portera l'extension .hs, il est le seul fichier reconnu par l'application. Il est au format XML. Il contient toutes les informations nécessaires à l'utilisation du manuel :

- la carte de correspondances (Map file) qui associe les identifiants des sujets du manuel à leur URL ou chemin de fichier respectif ;

- les informations de visualisation, c'est-à-dire la liste des composants de navigation utilisables. Ils peuvent être : la table des matières, l'index, le moteur de recherche par mots-clés, le glossaire, les favoris ;

- le titre du manuel (Helpset title) ;

- l'identifiant du sujet (Home ID) à afficher par défaut lors de l'ouverture du manuel ;

- les attributs de la fenêtre (Presentation) dans laquelle le manuel sera affiché ;

- d'autres fichiers HelpSet (Sub-helpsets) à fusionner (optionnel) ;

- d'autres informations relatives à l'implémentation d'un registre (Implementation) (optionnel).

XII - Exemple de fichier HelpSet

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE helpset
PUBLIC "-//Sun Microsystems Inc.//DTDJavaHelp HelpSet Version 2.0//EN"
"../dtd/helpset_2_0.dtd">
<helpsetversion="1.0">
<title>My SampleHelp -Online</title>
<maps>
<homeID>top</homeID>
<mapreflocation="Map.jhm"/>
</maps>
<view>
<name>TOC</name>
<label>Table Of Contents</label>
<type>javax.help.TOCView</type>
<data>SampleTOC.xml</data>
</view>
<view>
<name>Index</name>
<label>Index</label>
<type>javax.help.IndexView</type>
<data>SampleIndex.xml</data>
</view>
<view>
<name>Search</name>
<label>Search</label>
<type>javax.help.SearchView</type>
<dataengine="com.sun.java.help.search.DefaultSearchEngine">
JavaHelpSearch
</data>
</view>
<presentationdefault="true"displayviewimages="false">
<name>mainwindow</name>
<sizewidth="700"height="400" />
<location x="200" y="200" />
<title>My SampleHelp -Online</title>
<image>toplevelfolder</image>
<toolbar>
<helpaction>javax.help.BackAction</helpaction>
<helpaction>javax.help.ForwardAction</helpaction>
<helpaction>javax.help.SeparatorAction</helpaction>
<helpaction>javax.help.HomeAction</helpaction>
<helpaction>javax.help.ReloadAction</helpaction>
<helpaction>javax.help.SeparatorAction</helpaction>
<helpaction>javax.help.PrintAction</helpaction>
<helpaction>javax.help.PrintSetupAction</helpaction>
</toolbar>
</presentation>
<presentation>
<name>main</name>
<sizewidth="400"height="400" />
<location x="200" y="200" />
<title>My SampleHelp -Online</title>
</presentation>
</helpset>

XIII - La carte de correspondances

La carte de correspondances contient la liste des alias et les URL ou chemins de fichiers correspondant aux sujets du manuel.

Il est au format XML et d'extension jhm. Son élément racine est map.

L'élément mapID prend les attributs suivants :

Attribut

Description

target

Alias du sujet pointé

url

URL ou chemin de fichier du sujet

XIV - Exemple de carte de correspondances

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE map
PUBLIC "-//Sun Microsystems Inc.//DTDJavaHelp Map Version 1.0//EN"
"http://java.sun.com/products/javahelp/map_1_0.dtd">
<map version="1.0">
<mapID target="toplevelfolder" url="images/toplevel.gif" />
<mapID target="top" url="help/welcome.html" />
<mapID target="intro" url="help/welcome.html" />
<mapID target="start" url="help/start.html" />
<mapID target="overview" url="help/welcome.html" />
<mapID target="one" url="help/start.html" />
<mapID target="two" url="help/start.html" />
</map>

XV - La table des matières

La table des matières contient la liste structurée des liens vers les différents sujets du manuel.

C'est un fichier XML d'élément racine toc et porte l'extension xml. L'élément tocitem peut contenir 0 ou plusieurs autres tocitem. Un tocitem a les paramètres suivants :

Attribut

Description

text

le texte qui sera affiché

image

une icône devant le texte

target

l'alias du sujet pointé

expand

vaut true pour forcer l'affichage des sous-items

presentationname

le nom d'une fenêtre définie dans HelpSet

presentationtype

le nom d'un type de présentation : popup ou autre

XVI - Exemple de table des matières

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE toc
PUBLIC "-//Sun Microsystems Inc.//DTDJavaHelp TOC Version 2.0//EN"
"../dtd/toc_2_0.dtd">
<toc version="2.0">
<tocitem text="mon petit manuel" image="toplevelfolder">
<tocitem text="Introduction" target="intro"/>
<tocitem text="Tutoriel"target="start"expand="true">
<tocitem text="Preface" target="overview"/>
<tocitem text="chap1" target="un"/>
<tocitem text="chap2" target="deux"/>
</tocitem>
<tocitem text="Historique" target="story"/>
<tocitem text="Historique dans une autre fenêtre" target="story"
presentationtype="javax.help.SecondaryWindow"presentationname="main"/>
<tocitem text="Historique en Popup"target="story"
presentationtype="javax.help.Popup"/>
</tocitem>
</toc>

XVII - L'index

L'index contient une liste hiérarchique de mots-clés ou de concepts-clés faisant référence à des sujets du manuel.

C'est là encore un fichier XML portant l'extension xml. Son élément racine : index. Il contient des éléments indexitem. L'élément indexitem peut contenir 0 ou plusieurs autres indexitem. Un indexitem possède les attributs suivants :

Attribut

Description

text

le texte qui sera affiché

target

l'alias du sujet pointé

expand

vaut true pour forcer l'affichage des sous-items

XVIII - Exemple d'index

<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE index
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN"
"http://java.sun.com/products/javahelp/index_1_0.dtd">
<index version="1.0">
<indexitem text=".prof extension (profile data)" target="prof.profile"/>
<indexitem text="accelerators (keyboard), see 'keyboardcommands'"/>
<indexitem text="adding an existing project" expand="false">
<indexitem text="naming the project" target="proj.importdirectory"/>
<indexitem text="naming the storage directory" target="proj.importdirectory"/>
<indexitem text="procedures for" target="proj.importproject2"/>
</indexitem>
<indexitem text="arguments" expand="false">
<indexitem text="passing" target="debug.arguments"/>
<indexitem text="specifying" target="debug.arguments"/>
</indexitem>
</index>

XIX - Visualisation du manuel

En cours de débogage, voici une méthode simple :
créez dans un répertoire $MANUEL_HOME et entreposez-y tous les fichiers cités précédemment :

Fichier

Description

Map.jhm

Carte de correspondances

Sample.hs

Fichier HelpSet

SampleIndex.xml

Index

SampleTOC.xml

Table des matières

welcome.html

Page HTML par défaut du manuel

créez un sous-répertoire help\ et copiez-y le fichier welcome.html ;

ensuite, exécutez cette ligne de commande :

java -jar $JAVAHELP_HOME\demos\bin\hsviewer.jar -helpset $MANUEL_HOME\Sample.hs

XX - Archivage du manuel

Après cette visualisation de test, nous allons créer une archive JAR qui contiendra notre manuel :

syntaxe :

jar -cvf manuel.jar $MANUEL_HOME\*

et maintenant, visualisons le manuel archivé :

java -jar $JAVAHELP_HOME\demos\bin\hsviewer.jar -helpset $MANUEL_HOME\manuel.jar

XXI - Rendu final

Et voilà, notre manuel est opérationnel.

XXII - Création du moteur de recherche

Ce moteur permet de rechercher parmi les sujets du manuel des mots-clés. Les mots-clés seront mis en surbrillance dans le texte trouvé.

Pour être utilisé, il faut au préalable créer la base de données grâce à la commande jhindexer située dans le répertoire $JAVAHELP_HOME\javahelp\bin\.

Syntaxe :

$JAVAHELP_HOME\javahelp\bin\jhindexer welcome.html

Il en résulte la création du répertoire JavaHelpSearch\ qui contient toutes les données nécessaires au moteur de recherche.

XXIII - Test de la base de recherche

La commande jhsearch située dans le répertoire $JAVAHELP_HOME\javahelp\bin\ permet de tester la base de recherche.

Syntaxe :

$JAVAHELP_HOME\javahelp\bin\jhsearch JavaHelpSearch

Il s'affiche alors :

initialized; enter query

tapez un mot-clé ou quittez en tapant « . »

XXIV - Ajout de JavaHelp à votre application

import java.net.*;
import javax.help.*;
import javax.swing.*;
import java.awt.event.*;

public classHelpMenu{
JFramef;
JMenuItem topics;

public HelpMenu() {
f = newJFrame("Mon application");
JMenuBar mbar = new JMenuBar();

// menus Fichier et Aide
JMenu file = new JMenu("Fichier");
JMenuhelp = newJMenu("Aide");

// ajout d'un item dans le menu Aide
help.add(topics = new JMenuItem("Aide"));

// ajout des menus à la barre de menu
mbar.add(file);
mbar.add(help);

// création des objets HelpSet et HelpBroker
HelpSet hs = getHelpSet("Sample.hs");
HelpBroker hb = hs.createHelpBroker();

// affectation de l'aide au composant
CSH.setHelpIDString(topics, "top");

// gestion des évènements
topics.addActionListener(new CSH.DisplayHelpFromSource(hb));

// attachement de la barre de menu à la fenêtre
f.setJMenuBar(mbar);
f.setSize(500, 300);
f.setVisible(true);
}

public HelpSet getHelpSet(Stringhelpsetfile) {
HelpSet hs = null;
ClassLoader cl = this.getClass().getClassLoader();
try{
URL hsURL = HelpSet.findHelpSet(cl,helpsetfile);
hs = newHelpSet(null,hsURL);
} catch(Exceptione e) {
System.out.println("HelpSet: " + ee.getMessage());
System.out.println("HelpSet: " + helpsetfile + " non trouvé");
}
return hs;
}

public static void main(String argv[]) {
new HelpMenu();
}
}

XXV - Outils connexes

La création des fichiers de correspondances, d'index, etc. peut être générée par des outils graphiques.

XXVI - Historique

23 mai 2004 : création du document (27 diapos).

Agissez sur la qualité de ce document en envoyant vos critiques et suggestions à l'auteur.

Pour toute question technique, se reporter au forum Java de Developpez.com.

Reproduction autorisée uniquement pour un usage non commercial.

XXVII - Note et remerciement du gabarisateur

Cet article a été mis au gabarit de developpez.com. Voici le lien vers le PDF d'origine : javahelp.pdf.

Le gabarisateur remercie Claude LELOUP pour sa correction orthographique.