Mit Forrest Benutzerdokumentationen erzeugen

Die Ursache für mangelhafte Dokumentationen ist meist: Programmierer bauen lieber neue Features in ihre Software ein als alte Funktionen zu dokumentieren. Dabei ist es gar nicht so schwer, dem Programm zumindest so viel Informationen mitzugeben, dass auch andere Entwickler und Benutzer davon profitieren können. Schließlich ist das ja auch ein Grund dafür, Software samt Quellcode zu veröffentlichen.

Der Kasten "Schritte zur Dokumentation" gibt zunächst ein paar allgemeine Tipps für das Dokumentieren von Programmen. Im Mittelpunkt dieses Artikels steht dann aber das Tool Apache Forrest, das sehr ansprechende Dokumentationen erzeugt, ohne dass der Anwender großartige Kenntnisse im Webdesign braucht. Das Ergebnis lässt sich mit dem Code zusammen paketieren, man kann es auch gleichzeitig als Webauftritt des eigenen Projekts nutzen. Apache Forrest wird von Apache für einige Projekte wie Xml.apache.org selbst verwendet. Es hat also seine Nützlichkeit in einem größeren Umfeld bereits bewiesen.

Forrest erledigt natürlich nicht die inhaltliche Dokumentation, sondern nur die ansprechende Formatierung als HTML- und PDF-Dokument. Es genügt prinzipiell, die Doku-Seiten in einfachstem HTML zu schreiben, zum Beispiel die Tags »h1« und »p«. Mehr ist möglich, aber nicht unbedingt nötig.

Download und Installation

Die ersten Schritte sind der Download (aktuell ist die Version 0.7), die Installation sowie die Konfiguration der Benutzerumgebung. Am besten ist es, den gut 20 MByte großen Tarball von [1] herunterzuladen und ihn an einem geeigneten Ort zu entpacken, zum Beispiel im Verzeichnis »/usr/local«. Das Paket bringt eine ganze Reihe weiterer Tools mit, zum Beispiel Ant und Jetty, sodass zusätzliche Installationsschritte entfallen. Es setzt nur eine Java-Runtime-Umgebung voraus, das GNU-Pendant GCJ funktioniert allerdings nicht. Die folgenden Zeilen richten die Umgebung ein:

export FORREST_HOME=/usr/local/apache-forrest-0.7
export PATH=$PATH:$FORREST_HOME/bin

Der nächste Schritt - das lokale Generieren der Forrest-Dokumentation - ist ein bisschen schwieriger, denn in die Version 0.7 hat sich ein Fehler eingeschlichen, der ironischerweise die eigene Dokumentation betrifft. Warum bisher noch keine gepatchte Version erschienen ist, bleibt rätselhaft. Wer die Mühe des im Folgenden beschriebenen Workaround scheut, findet die Forrest-Hilfe auch online.

Versionskonflikt

Im Prinzip ist der Schritt sehr einfach, denn die Erzeugung von Dokumentationen ist schließlich das Kerngeschäft von Forrest. Man wechselt in das Verzeichnis »$FORREST_HOME/site-author« und führt den Befehl »forrest« aus. Wichtig ist, dass zumindest beim ersten Aufruf eine Verbindung zum Internet besteht, denn dabei lädt Forrest Plugins und Skins herunter - was es damit auf sich hat, erklärt der Artikel später.

Preis für die Aktualität sind Versions-Inkompatibilitäten. Die Dokumentation für Forrest 0.7 benötigt von zwei Plugins nicht die aktuellen, sondern ältere Versionen. Deshalb ist es erforderlich, in der Datei »$FORREST_HOME/site-author/forrest.properties« die Liste der Plugins in der letzten Zeile folgendermaßen zu verändern:

project.required.plugins=org.apache.forrest.plugin.input.dtdx-0.1,org.apache.forrest.plugin.input.projectInfo-0.1,...

Damit verwendet Forrest die Plugins »input« und »projectInfo« in der älteren Version 0.1.

Dass es bisher weder dieser kleine Workaround noch die Doku dazu auf die Forrest-Webseite geschafft haben, ist das einzig Enttäuschende an diesem Projekt und ein Beispiel für Dokumentation, wie sie nicht sein sollte: veraltet. Auf der Forrest-Mailingliste ist dies eine oft gestellte Frage, denn es trifft jeden, der die Doku lieber lokal hält. Mit der oben beschriebenen Änderung läuft die Generierung der Dokumentation innerhalb weniger Minuten durch. Insgesamt entstehen über 500 Seiten mit etwa 12 MByte.