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.
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
Die eigentliche Konvertierung erfolgt nach Installation der benötigten Software mit einem einfachen Aufruf direkt aus dem kivitendo-Installationsverzeichnis heraus:
./scripts/build_doc.sh
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.