© Werber 21, photocase.com

Da hat man endlich bei Sourceforge ein seit langem gesuchtes Programm gefunden, aber es zu benutzen scheitert an fehlender Dokumentation. Wer als Entwickler den Anwendern der eigenen Software dieses Los ersparen will, ist reif für Forrest.

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.

Grundlage: Cocoon

Bevor es an ein einfaches, aber sinnvolles Beispiel geht, etwas zur Philosophie von Forrest. Es basiert auf dem Publishing-Framework Cocoon, das schon mehrfach Thema im Linux-Magazin war. Cocoon ist an sich für dynamische Webanwendungen ausgelegt, Forrest beweist aber, dass es auch für die statische Output-Generierung sehr nützlich ist.

Forrest wandelt Eingabedateien (Quellen) mittels Cocoon in Ausgabedateien um. Das an sich ist noch kein Mehrwert und hilft auch nicht beim Ziel “Dokumentation leicht gemacht”. Sein eigentlicher Nutzen liegt darin, dass der Entwickler die Navigationsstruktur seiner Dokumentation sehr einfach festlegen (und ändern) kann, Forrest kümmert sich um das richtige Layout mit passender Menüstruktur. Quasi als Abfallprodukt erzeugt es noch die Doku als PDF (auch als Komplettdokument), was den einen oder anderen Nutzer freuen dürfte, der die Doku lieber in ausgedruckter Form auf der Couch studiert.

Abbildung 1 zeigt den Screenshot einer typischen, mit Forrest erzeugten Dokumentation. Es gibt zwei Navigationselemente: Reiter (Tabs) oben und eine geschachtelte Menüstruktur links. Die Menüstruktur ist vom jeweils ausgewählten Reiter abhängig.

Abbildung 1: Die mit Forrest erzeugte Dokumentation erlaubt eine Navigation über Reiter (Tabs) und Menüs.

XML-Konfiguration

Beide Navigationselemente (Menüs und Tabs) definiert man in den beiden zentralen Dateien »site.xml« und »tabs.xml«. Der Vorteil dieser Aufteilung ist, dass sie die logische Struktur der Dokumentation von der physischen Struktur (Verzeichnisse) entkoppelt. Im ersten Wurf wird jeder Entwickler zwar der Übersichtlichkeit halber versuchen logische und physische Struktur gleich zu halten, aber die Dokumentation lebt und verändert sich genauso wie das Programm selbst.

Das nun folgende Beispiel zeigt die wenigen Schritte bis zur professionell formatierten Dokumentation. Neben den beiden erwähnten Dateien muss nur eine weitere Datei etwas anpasst werden.

Los geht’s

Der erste Schritt ist der einfachste: Der Entwickler wechselt in das Zielverzeichnis seiner Dokumentation (etwa »~/src/meinprojekt/doc«) und führt das Kommando »forrest seed« aus. Damit ist der Samen für den Dokumentationsbaum gesät oder weniger poetisch: Der Befehl hat eine komplette Verzeichnisstruktur samt Beispieldateien für das Projekt erzeugt. Schon an dieser Stelle kann der Benutzer mit einem einfachen »forrest« die Beispieldokumentation rendern lassen. Das ist durchaus sinnvoll, denn das Beispiel verwendet so beinahe das gesamte Funktionsspektrum von Forrest und ist als Fundgrube sehr nützlich.

Für den ersten Seed-Schritt empfiehlt es sich, online zu sein, da Forrest im Beispielprojekt definierte Skins in der neuesten Version herunterlädt. Große Teile des Beispiels werden später entsorgt, aber im Moment sollen die überflüssigen Dateien nicht stören. Wer Forrest häufig verwendet, kann »$FORREST_HOME/main/fresh-site« anpassen und so ein eigenes Einstiegstemplate definieren.

Individueller Look

Das Beispiel sieht bisher noch sehr nach Forrest-Standard und nicht nach einem eigenen Projekt aus, deshalb steht an erster Stelle etwas Oberflächenpolitur. Das erledigt der Anwender in der Datei »src/documentation/skinconf.xml« unterhalb des Wurzelverzeichnisses, also im Beispiel »~/src/meinprojekt/doc/src/documentation/skinconf.xml«. Wem die Standardverzeichnisstruktur nicht gefällt, der kann sie über die Toplevel-Konfigurationsdatei »forrest.properties« anpassen.

Die Datei »skinconf.xml« enthält Attribute wie Projektname, Beschreibung, Logo und URL. Außerdem ist die Auswahl eines Themas (Skin) zur Anpassung des Aussehens möglich. Selbst bei ausgewähltem Skin lassen sich über CSS-Definitionen Defaultwerte (zum Beispiel Farben) überschreiben. Einen Ausschnitt der »skinconf.xml« zeigt Listing 1.

001: <?xml version="1.0"?>
010:
011: <!DOCTYPE skinconfig PUBLIC
012:     "-//APACHE//DTD Skin Configuration V0.7-1//EN"
013:     "http://forrest.apache.org/dtd/skinconfig-v07-1.dtd">
014:
015: <skinconfig>
016:   . . .
025:   <disable-compliance-links>false</disable-compliance-links>
026:
027:   <obfuscate-mail-links>true</obfuscate-mail-links>
028:   <obfuscate-mail-value> . a t . </obfuscate-mail-value>
029:
030:   <project-name>FIATK</project-name>
031:   <project-description>Fast Image-Archiving Toolkit</project-description>
032:   . . .
033:   <project-logo>images/project-logo.gif</project-logo>
034:
035:   <host-url></host-url>
036:   <host-logo></host-logo>
037:
038:   <favicon-url></favicon-url>
039:
040:   <year>2006-2007</year>
041:   <vendor>Bernhard Bablok</vendor>
042:
043:   . . .
048:
049:   <toc max-depth="2" min-sections="2" location="menu"/>
050:   <headings type="boxed"/>
051:   <feedback to="mail . at . bablokb.de"
052:     href="mailto:mail%20.%20at%20.%20bablokb.de?subject=Feedback&#160;" >
053:     Send feedback about the website to:
054:   </feedback>
055:
056:   <extra-css>
057:     p.quote {
058:       margin-left: 2em;
059:       padding: .5em;
060:       background-color: #f0f0f0;
061:       font-family: monospace;
062:     }
063:     #footer a { color: #0F3660; }
064:     #footer a:visited { color: #009999; }
065:   </extra-css>
066:
067:   <colors>
068:   </colors>
069:
070:   <pdf>
071:     <page size="a4" orientation="portrait" text-align="left"/>
072:     <page-numbering-format>Page 1</page-numbering-format>
073:
074:     <margins double-sided="false">
075:       <top>1in</top>
076:       <bottom>1in</bottom>
077:       <inner>1.25in</inner>
078:       <outer>1in</outer>
079:     </margins>
080:
081:     <show-external-urls>false</show-external-urls>
082:     <disable-copyright-footer>false</disable-copyright-footer>
083:   </pdf>
084:
085:   <credits>
086:     <credit box-location="alt">
087:       <name>Built with Apache Forrest</name>
088:       <url>http://forrest.apache.org/</url>
089:       <image>images/built-with-forrest-button.png</image>
090:       <width>88</width>
091:       <height>31</height>
092:     </credit>
093:   </credits>
094: </skinconfig>

Menüs und Tabs

Steht das Aussehen fest, geht es um Struktur und danach um Inhalt. Dazu dienen die schon erwähnten Dateien »site.xml« und »tabs.xml«. Beide Dateien finden sich im Verzeichnis »src/documentation/content/xdocs«. Es ist auch das Wurzelverzeichnis für alle Dokumentationsdateien, die jeder leider trotzdem noch selbst schreiben muss.

Die Abbildungen 1 und 2 illustrieren, zu welchem Ergebnis die Listings 2 und 3 führen. Vielleicht etwas überraschend und zunächst nicht intuitiv (man erwartet so viel Freiheit nicht): Der Anwender ist in der Wahl der (inneren) XML-Tags innerhalb von »site.xml« völlig frei. Da es nur darum geht, die Menüstruktur abzubilden, sind die eigentlichen Tag-Namen für die Menüs irrelevant.

Abbildung 2: Wenn der Benutzer den zweiten Reiter »Installation and Configuration« wählt, ändert sich auch der angezeigte Menüpunkt.

001: <?xml version="1.0" encoding="UTF-8"?>
009:
010: <site label="FIATK" href="" tab=""
011:   xmlns="http://apache.org/forrest/linkmap/1.0">
012:
013:   <!-- overview-tab -->
014:   <overview label="Overview">
015:     <welcome label="Welcome" href="index.html" description="Welcome to
016:       the Fast Image-Archiving Toolkit FIATK"/>
017:     <relnotes label="Release Notes" href="relnotes.html" />
018:   </overview>
019:
020:   <!-- installation-tab -->
021:   <install label="Installation and Configuration" tab="install"
022:    href="install/">
023:     <overview label="Overview"       href="index.html" />
024:     <download label="Download"       href="index.html#download" />
025:     <fiatkcore label="FIATK-Core Installation" href="index.html#core" />
026:     <exttools label="External Tools" href="index.html#ext-tools" />
027:     <config   label="Configuration"  href="config.html" />
028:   </install>
029:
030:   <!-- documentation-tab -->
031:   <docs label="Documentation" tab="docs" href="docs/">
032:     <index label="Overview"             href="index.html" />
033:     <qsguide   label="Quickstart-Guide" href="qs-guide.html" />
034:     <userguide label="User's-Guide"     href="users-guide.html" />
035:     <howtos    label="Howtos"           href="howtos.html" />
036:     <faqs      label="FAQs"             href="faqs.html" />
037:   </docs>
038:
039:   <!-- reference-tab -->
040:     <ref label="Command-Reference" tab="ref" href="ref/" >
041:       <index          label="Categories"     href="index.html" />
042:       <bdccal         label="bdccal"         href="bdccal.html" />
043:       <bdccomment     label="bdccomment"     href="bdccomment.html" />
044:       <bdcconvert     label="bdcconvert"     href="bdcconvert.html" />
045:       . . .
064:     </ref>
065:
066:   <!-- external references -->
067:   <external-refs>
068:     <image-magick href="http://www.imagemagick.org"/>
069:     <jpeg         href="http://www.ijg.org"/>
070:     <exiftran     href="http://linux.bytesex.org/fbida/"/>
071:     . . .
079:   </external-refs>
080:
081: </site>

001: <?xml version="1.0" encoding="UTF-8"?>
002:
010: <!DOCTYPE tabs PUBLIC
011:     "-//APACHE//DTD Cocoon Documentation Tab V1.1//EN"
012:     "http://forrest.apache.org/dtd/tab-cocoon-v11.dtd">
013:
014: <tabs software="FIATK"
015:   title="The Fast Image Archiving Toolkit"
016:   copyright="(c) Bernhard Bablok, 2004-2007"
017:   xmlns:xlink="http://www.w3.org/1999/xlink">
018:
019:   <tab id=""         label="Overview" dir="" />
020:   <tab id="install"  label="Installation and Configuration" dir="install"/>
021:   <tab id="docs"     label="Documentation" dir="docs"/>
022:   <tab id="ref"      label="Command-Reference" dir="ref"/>
023: </tabs>

Im ersten Tab »Overview« erscheinen alle Menüs (Abbildung 1) der Site. Die Struktur bildet Forrest 1:1 ab, das Label-Attribut gibt den Text im Menü an, »href« verweist auf die anzuzeigende Datei und »tab« steuert die Aufnahme des Menü-Item in die weiteren Reiter. Das ist in Abbildung 2 zu sehen: Hier ist der zweite Reiter mit der ID »install« (Listing 3, Zeile 20) ausgewählt. Damit rendert Forrest nur die entsprechenden Menü-Einträge aus der »site.xml« (Listing 2, Zeilen 20 bis 28).

So lassen sich sehr leicht mehrere Varianten ausprobieren. Wer zum Beispiel auf dem ersten Reiter tatsächlich nur das Overview-Menü darstellen will, muss nur die Tab-IDs anpassen. Bei verschachtelten Menüs finden eine Vererbung von Tab-Attributen und eine Verknüpfung von Href-Attributen statt. Letztere sind also relativ zum »href« des übergeordneten Menü-Eintrags.

Attribute zur Steuerung

In »tabs.xml« stehen ID-Attribute, die die Verknüpfung zu den Tab-Attributen in der »site.xml« herstellen, wie oben beschrieben. Ebenfalls vorhanden ist ein Label-Attribut. Die Attribute »dir«, »indexfile« und »href« legen die Seite fest, die im ausgewählten Reiter erscheint. Es genügt aber, wie in Listing 3, bereits das Dir-Attribut, um automatisch die Seite »index.html« im entsprechenden Verzeichnis anzuzeigen.

Nachdem die Oberfläche und die Struktur festgelegt sind, geht es an den Inhalt. Der Anwender kann jederzeit per »forrest« den aktuellen Stand rendern und sich anzeigen lassen. Links, die ins Leere gehen, vermerkt Forrest im Protokoll.

Wo die Doku herkommt

Forrest nutzt, wie schon erwähnt, das Framework Cocoon, um aus den Eingabedateien die Ausgabedateien im HTML- und PDF-Format zu erzeugen. Die im vorigen Abschnitt beschriebene Datei »site.xml« legt dabei die Zielstruktur des fertig gerenderten HTML fest, aus diesem Grund zeigen alle Referenzen auf HTML-Dateien. Die Quellstruktur liegt im »xdocs«-Verzeichnis und wird nach Cocoon-Regeln übersetzt. Die Quelldateien können, müssen aber nicht im HTML-Format vorliegen.

Aus »foo.html« wird zum Beispiel »foo.html« (aber nicht 1:1 kopiert), genauso könnte aber »foo.xml« die Quelle für »foo.html« sein. Der Vorteil: Vorhandene Doku lässt sich leichter übernehmen, Forrest sorgt für einheitliches Look&Feel. Wer auf der grünen Wiese anfängt, sollte einen Blick auf die Forrest-Beispiele werfen. Hier gibt es DTDs für allgemeine Dokumente, FAQs, Howtos und so fort. Der Anwender schreibt also strukturierte XML-Dokumente und Forrest kümmert sich um die adäquate Darstellung – ein Prozess, der Codern eigentlich sehr entgegenkommt.

Forrest ist sehr flexibel, wenn es um die Eingabedateien geht. Dabei kommen die Plugins ins Spiel. Mit etwas Java-Code kann der Anwender praktisch beliebige Eingabedateien verarbeiten. Für viele Dateitypen muss er aber nicht einmal selbst kodieren, entsprechende Plugins sind auf der Forrest-Website vorhanden und werden bei Bedarf automatisch heruntergeladen. Die Einbindung und Verarbeitung von exotischen Dateitypen erfordert allerdings etwas Konfigurationsarbeit, die in der Forrest-Dokumentation im Detail beschrieben ist.

Als weiteres Feature verwaltet Forrest auch Hyperlinks. Interne Links haben die Form »href=”site:Tag-Name”« wobei Tag-Name ein in »site.xml« definierter Knoten ist. Im Gegensatz zur Menüstruktur spielt hier der Tag-Name sehr wohl eine Rolle. Dabei kann der Benutzer Tag-Name absolut oder relativ angeben. Hat er eindeutige Namen vergeben, braucht er sich im Link nicht darum kümmern, wo in der logischen Struktur sich das Ziel findet, das erledigt Forrest während der Generierung. Wer seine Quellseiten irgendwann reorganisiert, muss seine Links nicht nachziehen.

Verweise auf externe Dokumente sind ähnlich einfach: Hier schreibt man »href=”ext:Tag-Name”«. Der Tag-Name ist hier ein Knoten unterhalb der Struktur »external-refs« in »site.xml« (siehe Listing 2, Zeilen 66 bis 79). Diese einfache Möglichkeit für Querverweise erweist sich in der praktischen Arbeit als ganz besonders nützlich. Statt ständig mit komplizierten relativen Referenzen auf Site-interne Dokumente zu hantieren, muss sich der Anwender nur eine einfache Syntax aneignen.

Entwicklungsprozess und Publishing

Für alle, die ihre eigene Dokumentenstruktur entwickeln oder viele Dokumente überarbeiten, ist der jeweilige Aufruf von »forrest« für das erneute Rendern der Dokumentation lästig – der Aufruf rendert alle Seiten aufs Neue. Hier hilft der eingebaute Servlet-Container Jetty: »forrest run« startet den Server auf Port 8888 (wie man den Port ändert, steht in den FAQ).

Damit wird die Dokumentation von Jetty (genauer von der Forrest-Webanwendung) dynamisch, also beim Abruf der entsprechenden Seite gerendert. Das beschleunigt den Entwicklungsprozess gewaltig, da der Benutzer natürlich nur noch selektiv die geänderten Dateien abruft und ihr Aussehen überprüft. Er sollte aber am Schluss eine Komplettgenerierung durchführen, da die Webanwendung nicht die DTD-Konformität validiert.

Reiche Ernte

Forrest ist ein nützliches Tool, das Software-Dokumentationen ansprechend formatiert. Das Ergebnis eignet sich sowohl für das Programmpaket zur Distribution, als auch für die Projekt-Homepage. Wer einen eigenen Server betreibt, bekommt durch den Forrest-Buildprozess eine komplette, deploybare Webanwendung (mit »forrest war«). Freunde von gedrucktem Papier verwenden die von Forrest parallel gerenderten PDF-Dokumente für schöne Ausdrucke ohne HTML-Overhead.

Durch seine Entstehung (und die DTDs) für die Generierung von statischer Dokumentation ausgelegt, bietet es sich natürlich auch an, mit Forrest kleinere Websites in einem einheitlichen Look&Feel zu erstellen und zu verwalten. Als kostenlose Dreingabe entsteht damit eine fertige Cocoon-Umgebung ohne den entsprechenden Installations- und Konfigurationsaufwand. (ofr)