Si, comme moi, vous avez déjà du réaliser des fichiers d’aide, vous êtes surement tombé sur la spécification JavaHelp (version 1.0 et version 2.0). Vous avez probablement immédiatement apprécié son intégration à Swing, son support pour l’internationalisation, l’indexation, la possibilité de réaliser vos fichiers d’aide en pur HTML, de pouvoir fusionner des fichiers d’aide au vol et la possibilité de mise à jour par réseau de ces fichiers.

Et puis, après quelques essais, vous avez déchanté. Vous avez vu à quoi ressemblait un ficher HTML affiché avec JavaHelp et vous avez vraiment hésité avant d’intégrer cette technologie dans votre application. Parce que, il faut vraiment l’admettre, malgré toutes ses promesses, JavaHelp a visuellement l’air coincé dans les années 1990!

Note préliminaire: Le code est en dernière page et ce document est un document technique expliquant comment améliorer la visioneuse de JavaHelp. Il n’a pas pour but de vous expliquer comment utiliser JavaHelp ou rédiger votre documentation.

Pourquoi?

Si l’on s’intéresse de près à la spécification JavaHelp, on remarquera inévitablement une petite note précisant que, par défaut, la visionneuse repose sur le composant Swing JEditorPane. Et que savons nous, par expérience, sur ce composant lorsqu’il affiche du HTML?

• Pas de support pour l’antialiasing des polices
• Pas de support pour le javascript
• Pas de support pour le XHTML. N’écrivez jamais <br/>, écrivez toujours <BR>
• Un support CSS quasi inexistant
• En général un rendu à des lieues du rendu d’un navigateur moderne

En fait, historiquement, le JEditorPane date des années 1990, au tout début de l’ère Swing. Ainsi, lorsqu’il prétend supporter le format RTF de microsoft, ce n’est que partiel et uniquement les fichiers tels que Word97 le créait. Inutile de faire un fichier RTF avec office 2003 et espérer l’afficher dans le JEditorPane.

Il en va de même pour le HTML. La norme supportée est le « HTML 3.2/CSS1″, paire de standards qui datent de ….1997 ! Et comme avec le RTF, le support n’est que partiel. Par exemple, les propriétés CSS doivent être écrites entièrement en minuscules.

Le problème de cette norme, c’est qu’on ne peut pas en faire grande chose de visuellement attractif. Les documentations que vous allez générer avec cette norme seront assez austères. Je suis par ailleurs tombé sur plusieurs billets sur le net maudissant JavaHelp pour cette raison.

Comment faire un logiciel professionnel aujourd’hui quand on est à peine capable de changer la police dans son fichier d’aide? Et que dire quand les images s’affichent à la mauvaise taille ou sont déformées dans l’aide? J’ai par ailleurs trouvé des outils commerciaux de rédaction de fichiers d’aide qui avaient arrêté de supporter JavaHelp comme format de sortie, vu le nombre d’horreur graphiques que cela générait d’après eux.

Il faut cependant poser un petit bémol à ce tableau bien noir. J’ai fait des tests sous java 6 et cette version semble capable d’afficher des fichiers XHTML4 avec du CSS un peu avancé, comme vous le verrez dans les captures d’écran plus loin. Mais il reste de nombreux bugs et ceux-ci peuvent vite devenir un cauchemard pour vos rédacteurs de documentation.