Online-Hilfen und Dokumentationen sind ungeliebte Pflichtaufgaben jedes Programmierers, doch der Erfolg eigener Programme hängt oft genau davon ab. Java Help ist ein Tool, mit dem Online-Hilfen auf sehr einfache Art in eigene Programme eingebunden werden können.

Online-Hilfen sind nicht notwendig – das ist eine teilweise berechtigte Einstellung mancher Programmierer. Und in der Tat, Programme sollten intuitiv zu bedienen sein und genau das tun, was von ihnen erwartet wird. Und für eine »Datei | Sichern als…«-Operation wird auch kein vernünftiger Mensch eine umfangreiche Hilfe benötigen.

Aber das ist nur die eine Seite der Medaille. Nicht-triviale Programme führen auch nicht-triviale Operationen durch, und diese bedürfen in der Regel einer Hilfe. Je komplexer ein Programm wird, umso notwendiger ist diese Funktion.

Bei vielen Programmen, zum Beispiel Spreadsheets, wird es sogar so sein, dass eine Reihe von Funktionen extrem selten benötigt wird – aber jedes Mal eine andere davon. Ohne sinnvolle Hilfe deinstalliere ich dann Programme wieder, bei denen ich nicht weiterkomme, oder ich verschwende meine Zeit mit dem Ausprobieren.

All diese Argumente gelten auch für Java-GUI-Anwendungen. Anwendungen auf dem Desktop spielen zwar nicht die Rolle, von der viele geträumt haben, aber tot ist Java deshalb auf dem Client noch lange nicht. Selbst bei Server-basierten Java-Anwendungen finden sich immer wieder kleine Administrationsdialoge mit grafischer Oberfläche, die die Konfiguration und Überwachung auf einfache Weise zur Verfügung stellen.

Java Help ist eine reine Java-Anwendung, die es schon seit drei Jahren gibt. Sie besteht einerseits aus einem Konzept – wie organisiere ich meine Hilfedateien – und andererseits aus den notwendigen Tools, um die Dateien dann anzuzeigen. Die kompilierten Klassen, die für diesen Zweck notwendig sind, dürfen frei mit eigenen Anwendungen verteilt werden. Der Quellcode wird auch mitgeliefert, aber Open Source ist dies noch lange nicht. Er dient nur zur Illustration und darf weder verändert noch weitergegeben werden. Manche Firmen haben noch einen weiten Weg vor sich.

Download und Installation

Der Download erfolgt wie üblich bei Java über die Seiten bei Sun (siehe[1]), nachdem die Lizenzvereinbarung akzeptiert wurde. Aktuell ist die Version 1.1.2_01, die in zwei Teilen heruntergeladen werden muss: einmal Java Help 1.1, anschließend noch das Patch auf 1.1.2_01.

Wer schon ein JDK oder zumindest ein JRE auf seiner Maschine hat, sollte aufpassen: Es gibt eine Version mit und eine Version ohne Java-Runtime. Letztere ist die richtige, sie ist aber immer noch fast 8,4 MByte groß. Das Patch kommt mit knapp 1,5 MByte daher.

Die eigentliche Java-Help-Runtime, die auch mit eigenen Programmen verteilt werden darf, ist deutlich kleiner, je nach Funktionsumfang, beispielsweise mit oder ohne Volltextsuche, sind es zwischen 220 und 400 KByte.

Die Installation ist simpel. Die heruntergeladene Datei »javahelp1_1-unix-no _rt.bin« wird ausführbar gemacht (mit »chmod +x«) und anschließend aufgerufen. Das Programm sucht nach vorhandenen Java-Versionen im »PATH« und stellt sie zur Auswahl. Nach der Wahl der entsprechenden Version (in der Regel sollte hier sowieso nur ein JDK/JRE im Pfad vorhanden sein) startet Install Anywhere. Der Rest läuft ab wie bei der Installation von Windows-Programmen gewohnt.

Um die Installation des Patches zu erleichtern ist es empfehlenswert, als Zielverzeichnis »/usr/local/jh1.1.2« zu verwenden (nur der letzte Bestandteil des Pfades ist dabei wichtig). Dadurch kann das Patch sehr einfach mit

# unzip javahelp-1_1_2_01.zip -d /usr/local/

eingespielt werden (es besteht aus neueren Versionen der Java-Help-Jars).

Abbildung 1: Java Help als Dokumentationsbrowser.

Erste Schritte

Java Help enthält einen Users Guide, der sowohl in HTML als auch im PDF-Format vorliegt. Neben Browser und Acrobat Reader kann auch das Java-Help-System selbst verwendet werden, um die Hilfe anzuzeigen, denn Java Help basiert auf HTML 3.2 (siehe Abbildung 1).

Wer die KDE-2-Hilfe kennt, wird sich sofort zurechtfinden. Links gibt es eine Navigationsleiste, die entweder ein Inhaltsverzeichnis, einen Index oder eine Volltextsuche bietet. Rechts im Hauptfenster wird der Hilfetext angezeigt.

Das implementierte Konzept hat zwei Vorteile: Erstens ist HTML ein Standard, so dass keine neue Auszeichnungssprache zu lernen ist. Zweitens kann die Hilfe so geschrieben werden, dass sie gleichzeitig als Dokumentation dient, also schon vor dem Programmaufruf zur Verfügung steht.

Der Users Guide führt umfassend in die Verwendung von Java Help ein. Dabei sind zwei Blickwinkel wichtig, die des Hilfe-Autors und die des Programmierers. Zusätzlich gibt es noch ein Verzeichnis »demos«, das insbesondere für Programmierer interessant ist.

Die Architektur

Eine Anwendung oder ein Applet, das über Java Help die Hilfe bereitstellt, besteht aus drei Teilen. Der Anwendung selbst, dem Help Viewer sowie den Hilfe-Dateien (einschließlich Metadaten). Letztere heißen in der Java-Help-Terminologie Help Set.

Da der Help Viewer auf Java-Swing basiert, kann er auch in die Anwendung integriert werden (Embedded Viewer). Eine weitere Option wäre ein Help Server, der als eigenständiger Prozess läuft und über RPC-Mechanismen (etwa RMI oder Corba) Hilfe-Anfragen ausführt. Über diesen Weg wäre Java Help auch von beliebigen (Nicht-Java-)Anwendungen aus nutzbar.

Die Hilfeseiten selbst können lokal vorliegen oder über das Netzwerk geladen werden. Letztere Option ist natürlich für Applets interessant, aber auch Java-Anwendungen in Firmennetzen könnten davon profitieren.

01: <?xml version='1.0' encoding='ISO-8859-1' ?>
02: <!DOCTYPE helpset
03:   PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
04:          "http://java.sun.com/products/ javahelp/helpset_1_0.dtd">
05:
06: <helpset version="1.0">
07:   <!-- title -->
08:   <title>The WebSync User's Guide</ title>
09:
10:   <!-- maps -->
11:   <maps>
12:      <homeID>top</homeID>
13:      <mapref location="websync.jhm"/>
14:   </maps>
15:
16:   <!-- views -->
17:   <view>
18:     <name>TOC</name>
19:     <label>Table Of Contents</label>
20:     <type>javax.help.TOCView</type>
21:     <data>websyncTOC.xml</data>
22:   </view>
23:
24:   <view>
25:     <name>Index</name>
26:     <label>Index</label>
27:     <type>javax.help.IndexView</type>
28:     <data>websyncIndex.xml</data>
29:   </view>
30:
31: <!-- No search view, since application is just too small
32:   <view>
33:     <name>Search</name>
34:     <label>Search</label>
35:     <type>javax.help.SearchView</type>
36:     <data engine="com.sun.java.help.search. DefaultSearchEngine">
37:       WebSyncSearchDataDir
38:     </data>
39:   </view>
40: -->
41: </helpset>

Organisation der Hilfedateien

Die Hilfedateien bestehen einmal aus den eigentlichen HTML-Hilfeseiten, den so genannten Topic Files, sowie verschiedenen Metadaten-Dateien. Der Name Topic File rührt daher, dass über ein Topic, einem eindeutigen Begriff, auf die Hilfeseiten zurückgegriffen wird. Es gibt folgende Metadaten:

• das Inhaltsverzeichnis,
• den Index,
• die DB für die Volltext-Suche,
• das Help Set File,
• das Map File.

Die ersten drei Dateien heißen auch Navigationsdateien. Während die Datenbank für die Volltextsuche über ein Java-Help-Tool erzeugt wird, müssen das Inhaltsverzeichnis und der Index von Hand oder durch ein Autorensystem erzeugt werden.

Die letzten beiden Metadateien sind die wichtigsten: Das so genannte Help Set File und das Map File. Hier ist Sun wieder eine verwirrende Namensgebung geglückt: Alle Hilfedateien zusammen heißen Help Set, und jedes Help Set enthält (gewissermaßen als Master-Index) ein Help Set File.

Im weiter unten beschriebenen Beispiel wird aber trotzdem schnell klar, welche Datei was tut. Letztlich ist das Help Set File die Datei, die von der Anwendung gelesen wird. Sie enthält Referenzen zu allen anderen Metadateien, sowohl bezüglich der Navigation als auch zu Map- und Topic-Dateien.

Die Map-Datei ist, wie der Name vermuten lässt, eine Zuordnung des Hilfebegriffs (Topic) zu einer URL mit der eigentlichen Hilfe. Auch diese Datei muss von Hand erzeugt werden, solange es noch keine Autorensysteme für Java Help gibt.

Alle Hilfedateien können in eine Jar-Datei verpackt werden; für Produktionsversionen ist das ein sinnvoller Weg der Distribution. Während der Entwicklung bietet es sich aber an, normal im Dateisystem zu arbeiten.

01: <?xml version='1.0' encoding='ISO-8859-1' ?>
02: <!DOCTYPE map
03:   PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"
04:          "http://java.sun.com/products/javahelp/map_1_0.dtd">
05:
06: <map version="1.0">
07:   <mapID target="top" url="intro.html" />
08:   <mapID target="mainwindow" url="mainwindow.html" />
09:   <mapID target="batch" url="batch.html" />
10:   <mapID target="configdialog" url="configdialog.html" />
11:   <mapID target="ftpusername" url="configdialog.html#ftpusername" />
12:   <mapID target="syncdialog" url="syncdialog.html" />
13:   <mapID target="logleveldialog" url="logleveldialog.html" />
14: </map>

01: <?xml version='1.0' encoding='ISO-8859-1'  ?>
02: <!DOCTYPE toc
03:   PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 1.0//EN"
04:          "http://java.sun.com/products/javahelp/0toc_1_0.dtd">
05:
06: <toc version="1.0">
07: <tocitem text="The WebSync User's Guide" image="websync" target="top">
08:
09:    <tocitem text="Introduction" target="top"/>
10:
11:    <tocitem text="The WebSync-GUI" target="mainwindow">
12:      <tocitem text="The Main Window" target="mainwindow"/>
13:      <tocitem text="The Configuration-Dialog" target="configdialog"/>
14:      <tocitem text="The Sync-Dialog" target="syncdialog"/>
15:      <tocitem text="The Log-Level-Dialog" target="logleveldialog"/>
16:    </tocitem>
17:
18:    <tocitem text="Batch-Mode" target="batch"/>
19: </tocitem>
20: </toc>

Ein Beispiel

Als Beispiel dient die Anwendung Websync (siehe[2],[3]), die ich verwende, um meine Webseiten von einem lokalen Verzeichnis aus zu synchronisieren. Das Help Set File ist in Listing 1 zu sehen. Neben der Map-Datei (Listing 2) werden zwei (Inhaltsverzeichnis und Index) der drei Standard-Views definiert (auf die Volltextsuche habe ich jedoch verzichtet, da sie bei einer so kleinen Anwendung mit beschränkten Hilfetexten Overkill gewesen wäre).

Wie zu sehen ist, sind die XML-Dateien (Listing 3 und 4) sehr einfach aufgebaut, also auch mit einem normalen Editor zu schreiben. Ein Grundgerüst für beide Dateien lässt sich auch mit einem simplen Skript (»grep« auf die H[1-6]-Tags) erzeugen.

Der Zugriff auf die Online-Hilfe ist mit wenigen Zeilen getan. Zuerst erfolgt der Zugriff auf das Help Set File (Zeilen 300-301 in Listing 5). Im Beispiel wird nicht über das Netz gesucht, sondern lokal im »CLASSPATH«. Wird also die gesamte Hilfe (mit den Metadaten) in einer Jar-Datei verpackt, muss diese auch im »CLASSPATH« vorhanden sein.

Aus dem so erzeugten Help-Set-Objekt wird wiederum ein Help-Broker-Objekt generiert. Die Anwendung interagiert jetzt nur noch über den Help Broker. In Zeile 304 wird die Hilfetaste, also [F1], mit dem Help-Target »top« verbunden. In Zeile 109 wird ein »MenuItem« mit einem »JavaHelp-ActionListener« verbunden, der die Default-Ansicht der Hilfe anzeigt.

Die verschiedenen APIs des Help Brokers erlauben es, jeder Komponente ein eigenes Topic, also damit über die Map-Datei ein eigenes Help-Target zuzuordnen. Ebenso ist es möglich, einen Hilfeknopf zu definieren, den man anklickt und anschließend jene Komponente auswählt, über die man mehr wissen will (eine Technik, die auch von KDE implementiert wird). Tool Tips (auch Fly-Over-Help genannt), wären hierzu aber eine etwas einfachere Alternative.

Was noch drinsteckt

Java Help bietet noch eine Reihe Finessen mehr, etwa die Lokalisierung der Hilfe. Hierbei wird automatisch zuerst nach lokalisierten Versionen gesucht (eine Funktion von »HelpSet.findHelpSet()«, siehe Zeile 300 in Listing 5).

Help Sets können auch zusammengefasst werden. Diese Funktion ist sowohl bei der Lokalisierung nützlich als auch bei Anwendungen, die aus mehreren Komponenten bestehen.

Die Volltextsuche wurde bereits erwähnt. Ein mit Java Help mitgeliefertes Tool indiziert dazu alle Hilfeseiten. Die dadurch erzeugten Dateien müssen dann zusammen mit den anderen Hilfedateien zur Verfügung gestellt werden, damit eine Volltextsuche im Hilfe-Viewer möglich ist.

Begrüßenswert wäre es übrigens, dass Sun den Viewer aus seinem Demo-Status befreit und bei der Gelegenheit den Aufruf etwas komfortabler gestaltet. Es handelt sich hier nämlich wirklich um ein sehr sinnvolles Tool. Details hierzu und zu anderen Aspekten von Java Help können dem sehr guten Users Guide entnommen werden. Da er auch als Quelle zur Verfügung steht, können seine Metadateien auch als Vorlagen für eigene Dateien dienen.

Es wurde oben schon angesprochen, dass die Hilfe auch als Dokumentation unabhängig von der Anwendung betrachtet werden kann. Der Aufruf ist etwas kompliziert, deshalb sei er hier kurz aufgeführt:

> /usr/local/jh1.1.2/demos/bin/hsviewer 
  -helpset /home/Bablokb/src/WebSync/help /websync.hs

Wer Dokumentation nicht über eine Java-Anwendung ansehen will, kann natürlich auch die rohen HTML-Seiten verwenden. Dann ist es aber auch Aufgabe des Autors, für eine sinnvolle Verlinkung zu sorgen. Eine weitere Alternative ist die Umwandlung nach Postscript über das Perl-Skript »html2ps«.

01: <?xml version='1.0' encoding='ISO-8859-1'  ?>
02: <!DOCTYPE index
03:   PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN"
04:          "http://java.sun.com/products/javahelp/ index_1_0.dtd">
05:
06: <index version="1.0">
07:
08: <!-- Symbol -->
09:
10: <!-- B -->
11:    <indexitem text="batch mode" target="batch" />
12:
13: <!-- C -->
14:    <indexitem text="config parameters" target="configdialog" />
15:
16: <!-- D -->
17:    <indexitem text="dry run" target="syncdialog" />
18:
19: <!-- F -->
20:    <indexitem text="file seperator" target="configdialog" />
21:    <indexitem text="files, excluding" target="configdialog" />
22:    <indexitem text="ftp username" target="ftpusername" />
23:    <indexitem text="ftp password:">
24:      <indexitem text="using the GUI" target="syncdialog" />
25:      <indexitem text="in batch-mode" target="batch" />
26:    </indexitem>
27:
28: <!-- L -->
29:    <indexitem text="local directory" target="configdialog" />
30:    <indexitem text="log file" target="configdialog" />
31:    <indexitem text="log level" target="logleveldialog" />
32:    <indexitem text="log window" target="mainwindow" />
33:
34: <!-- R -->
35:    <indexitem text="remote host" target="configdialog" />
36:
37: <!-- S -->
38:    <indexitem text="status file" target="configdialog" />
39:    <indexitem text="syncronization" target="syncdialog" />
40:
41:
42: </index>
43:

091:   private void jbInit() throws Exception  {
106:     iMenuHelp.setText("Help");
108:     iMenuHelpGuide.setText("User's Guide");
109:     iMenuHelpGuide.addActionListener(new CSH.DisplayHelpFromSource(iHelpBroker));
275:   }
276:
299:   private void initHelp() throws Exception {
300:     URL hsURL = HelpSet.findHelpSet(null, "help/websync.hs");
301:     HelpSet hs  = new HelpSet(null, hsURL);
302:     iHelpBroker = hs.createHelpBroker();
303:     JRootPane root = this.getRootPane();
304:     iHelpBroker.enableHelpKey(root,"top",null);
305:   }

finally{}

Für Java Help sind nur wenige Zeilen Code notwendig – allerdings an vielen verschiedenen Stellen. Deshalb macht es Sinn, eine Anwendung von Anfang an darauf auszulegen, eine kontextsensitive Hilfe anzubieten.

Intern verwendet Java Help reines Swing – ein Beweis dafür, wie mächtig dieses GUI-Toolkit ist. Die HTML-Rendering-Engine hat allerdings – zumindest unter Linux – noch ein paar Probleme mit PNG-Bildern und Fonts, wie ich festgestellt habe. Aber das ist kein Java-Help-spezifisches Problem, da hier die entsprechende Swing-Funktionalität verwendet wird.

Mit Java Help gibt es eine Ausrede weniger dafür, Programme ohne adäquate Hilfe zu verteilen. Also, ran an den HTML-Editor! (uwo)