4.7. Dokumentation erstellen

4.7.1. Einführung

Diese Dokumentation ist in DocBook™ XML geschrieben. Zum Bearbeiten reicht grundsätzlich ein Text-Editor. Mehr Komfort bekommt man, wenn man einen dedizierten XML-fähigen Editor nutzt, der spezielle Unterstützung für DocBook™ mitbringt. Wir empfehlen dafür den XMLmind XML Editor, der bei nicht kommerzieller Nutzung kostenlos ist.

4.7.2. Benötigte Software

Bei DocBook™ ist Prinzip, dass ausschließlich die XML-Quelldatei bearbeitet wird. Aus dieser werden dann mit entsprechenden Stylesheets andere Formate wie PDF oder HTML erzeugt. Bei kivitendo übernimmt diese Aufgabe das Shell-Script scripts/build_doc.sh.

Das Script benötigt zur Konvertierung verschiedene Softwarekomponenten, die im normalen kivitendo-Betrieb nicht benötigt werden:

  • Java in einer halbwegs aktuellen Version

  • Das Java-Build-System Apache Ant

  • Das Dokumentations-System Dobudish für DocBook™ 4.5, eine Zusammenstellung diverser Stylesheets und Grafiken zur Konvertierung von DocBook™ XML in andere Formate. Das Paket, das benötigt wird, ist zum Zeitpunkt der Dokumentationserstellung dobudish-nojre-1.1.4.zip, aus auf code.google.com bereitsteht.

Apache Ant sowie ein dazu passendes Java Runtime Environment sind auf allen gängigen Plattformen verfügbar. Beispiel für Debian/Ubuntu:

apt-get install ant openjdk-7-jre

Nach dem Download von Dobudish muss Dobudish im Unterverzeichnis doc/build entpackt werden. Beispiel unter der Annahme, das Dobudish™ in $HOME/Downloads heruntergeladen wurde:

cd doc/build
unzip $HOME/Downloads/dobudish-nojre-1.1.4.zip

4.7.3. PDFs und HTML-Seiten erstellen

Die eigentliche Konvertierung erfolgt nach Installation der benötigten Software mit einem einfachen Aufruf direkt aus dem kivitendo-Installationsverzeichnis heraus:

./scripts/build_doc.sh

4.7.4. Einchecken in das Git-Repository

Sowohl die XML-Datei als auch die erzeugten PDF- und HTML-Dateien sind Bestandteil des Git-Repositories. Daraus folgt, dass nach Änderungen am XML die PDF- und HTML-Dokumente ebenfalls gebaut und alles zusammen in einem Commit eingecheckt werden sollten.

Die "dobudish"-Verzeichnisse bzw. symbolischen Links gehören hingegen nicht in das Repository.