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 :

Image non disponible

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 :

 
Sélectionnez
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

 
Sélectionnez
<!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

 
Sélectionnez
<?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

 
Sélectionnez
<?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

 
Sélectionnez
<?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

 
Sélectionnez
<?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 :

 
Sélectionnez
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 :

 
Sélectionnez
jar -cvf manuel.jar $MANUEL_HOME\*

et maintenant, visualisons le manuel archivé :

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

XXI. Rendu final

Et voilà, notre manuel est opérationnel.

Image non disponible

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 :

 
Sélectionnez
$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 :

 
Sélectionnez
$JAVAHELP_HOME\javahelp\bin\jhsearch JavaHelpSearch

Il s'affiche alors :

 
Sélectionnez
initialized; enter query

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

XXIV. Ajout de JavaHelp à votre application

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