Blog Docbook - Integration in der Praxis

Docbook - Integration in der Praxis

Nach einer kurzen Vorstellung von Docbook in diesem Artikel, m├Âchte ich an dieser Stelle einmal darstellen, wie sich das System bei uns in der Praxis bew├Ąhrt hat. Hierbei werde ich nicht auf das Erstellen eines Dokumentes mit Docbook eingehen. Im Netz gibt es zahlreiche HowTos, die dies bereits sehr gut erkl├Ąren. Hier soll die Integration in ein bestehendes Entwicklungssystem aufgezeigt werden.

Docbook ist kein Programm im eigentlichen Sinne, sondern ein System bestehend aus DTDs (Document Type Definitions), den XSLs (XML-Stylesheets), einem Editor sowie einem XSLT-Prozessor zur Transformation der XML-Dokumente. Der Build-Prozess ist plattformunabh├Ąngig und kann beispielsweise durch ein Shellskript, mit Hilfe von Ant oder auch Maven definiert werden. Die Werkzeugkette bei n-design beinhaltet unter anderem Tools wie Eclipse, Maven, SVN und GIT sowie Jenkins zur Unterst├╝tzung des kontinuierlichen Entwicklungsprozesses. Jeder unserer Mitarbeiter kennt diese Werkzeuge und die meisten arbeiten t├Ąglich mit ihnen. Was liegt also n├Ąher, als auch Docbook in diesen Arbeitsablauf zu integrieren.

Eclipse

Eclipse w├╝rde bereits ohne weitere Plugins mit Docbook umgehen k├Ânnen, da wir uns alles N├Âtige ├╝ber Maven-Plugins bereitstellen lassen. Jedoch k├Ânnen wir uns viel Arbeit ersparen, indem wir das Eclipse-Plugin DEP4E (Docbook Editing and Processing for Eclipse) installieren. DEP4E verwendet eigentlich Ant f├╝r den Build-Prozess, stellt aber zus├Ątzlich f├╝r unsere Zwecke n├╝tzliche Ansichten, den Docbook XML Markup Editor und eine Pr├╝fung der XML-Struktur im Dokument gegen die entsprechenden XSL-Dateien zur Verf├╝gung. Alles Punkte, die wir nicht mehr manuell in Eclipse einstellen m├╝ssen.

Maven

Zur Erstellung von Docbook-Dokumenten verwenden wir in einem ├╝blichen Maven-Projekt das Maven-Plugin docbkx-maven-plugin aus der Gruppe com.agilejava.docbkx. Um einigen Fehlern im aktuellen Release aus dem Wege zu gehen, verwenden wir direkt das Snapshot-Repository. Docbkx bringt Saxon als XSLT-Prozessor sowie Apache's FOP zur Erzeugung von PDF- und RTF-Dokumenten bereits mit.

Die Ausf├╝hrungsebene (<execution>) muss entsprechende goals enthalten, um Ausgabeformate wie HTML, RTF, EPUB3 und PDF generieren zu k├Ânnen. In der Konfigurationsebene des Plugins (<configuration>) k├Ânnen dann diverse Einstellungen zu den einzelnen Formaten definiert werden. Die Dokumentation von Docbkx ist hier sehr ausf├╝hrlich und beinhaltet viele n├╝tzliche Beispiele. Eine der wichtigsten Einstellungen in diesem Bereich ist der Verweis auf die benutzerdefinierten XSL-Dateien f├╝r unsere Dokumente. Die von Docbook mitgelieferten Stylesheets sollten nicht ver├Ąndert werden. Anpassungen, beispielsweise f├╝r Kopf- und Fu├čzeilen in einer PDF-Ausgabe, m├╝ssen in einer eigenen XSL-Datei vorgenommen werden. Diese beinhaltet au├čer den individuellen Anpassungen auch immer einen Verweis auf das eigentliche Stylesheet, erbt sozusagen davon. Ein Start des Maven-Builds mit den goals clean und pre-site erstellt alle definierten Ausgabeformate.

Jenkins

Abschlie├čend erstellen wir auf unserem Jenkins-Server noch einen Job, der uns unser Dokument bei jeder ├änderung und einmal nachts (als nightly-build) erstellt. Wie bei jedem anderen Job, werden die Entwickler bei Fehlschl├Ągen benachrichtigt, k├Ânnen durch die Log-Ausgaben und dem im Versionskontrollsystem hinterlegten Code die ├änderungen verfolgen und anpassen.

Fazit

Die Integration von Docbook bei n-design hat sich vom technischen Aspekt her als relativ problemlos erwiesen. An einigen Stellen musste noch einmal gefeilt werden. So erwies sich Apache's FO-Prozessor in der Version 1.1 als noch nicht ganz ausgereift f├╝r die RTF-Erstellung. Eine Umstellung auf die Version 1.0 war n├Âtig. Auch die Formatierung der XML-Dateien im Editor ist nicht ganz wie erwartet: Block-Elemente (z.B. <para>) werden anders behandelt als sog. inline tags (z.B. <emphasis>), nach denen immer wieder ein Zeilenumbruch eingef├╝gt wird. Dies ergibt auch im erstellten Dokument unsch├Âne Leerzeichen bzw. Umbr├╝che. Hier sollten alternative Editoren unter Eclipse in Betracht gezogen werden.

Aus Sicht der Mitarbeiter, die sich in Docbook einfinden durften, konnten wir feststellen, dass sich die Einarbeitungszeit in Grenzen gehalten hat, da die meisten bereits vorher mit unserer Werkzeugkette gearbeitet haben. Allerdings erwies es sich als gew├Âhnungsbed├╝rftig, die nicht immer ganz aussagekr├Ąftigen Konsolenausgaben des XSLT- oder FO-Prozessors zu interpretieren. Der gr├Â├čte Vorteil ist jedoch die Tatsache, dass diese Form des Dokumentierens den meisten Mitarbeitern sehr viel n├Ąher liegt, als in der urspr├╝nglichen Form (mit Hilfe von WYSIWYG-Editoren). Das hat zur Folge, dass die Dokumentation weniger stiefm├╝tterlich behandelt wird und als st├Ąndiger Teil unseres kontinuierlichen und iterativen Entwicklungsprozesses akzeptiert wird. Durch die M├Âglichkeit der schnellen Anpassung, Wartung und der Nachvollziehbarkeit von ├änderungen stellt die Einf├╝hrung von Docbook f├╝r n-design einen klaren Mehrwert dar.