© pixpack, 123RF.com

Docbook gilt als Nonplusultra der technischen Dokumentation. Dieser Artikel zeigt, dass der Einstieg in die XML-Anwendung gar nicht schwer ist. Als Belohnung winken PDFs, E-Books und Manpages.

Docbook ist ein in XML umgesetztes Dokumenten-Beschreibungssystem [1]. Es besteht aus einer XML-Grammatik und einer Sammlung von XSLT-Stylesheets für Transformationen. In der Welt der technischen Dokumentation stellt das Docbook-Format einen weitverbreiteten Standard dar.

Gestaltungsfreiheit

Ein entscheidendes Merkmal von Docbook ist, dass Dokumenteninhalt und Layout vollkommen voneinander getrennt bleiben: So wird etwa ein in der Quelldatei in »<emphasis>« -Tags eingefasster Textabschnitt per Voreinstellung zwar kursiv gesetzt, lässt sich aber grundsätzlich völlig beliebig weiterverarbeiten.

Mit Docbook lässt sich eine ganze Reihe von Zielformaten erzeugen. Dazu gehören die Webstandards HTML und XHTML, außerdem das Zwischenformat XML-FO, aus dem der Benutzer unter anderem PDF-Dokumente zu gewinnen vermag. Das E-Book-Format Epub kann man in Version 2 und 3 exportieren, daneben eine ganze Reihe von Spezialformaten wie zum Beispiel Linux-Manpages.

Docbook hat seinen Ursprung in der Soft- und Hardware-Dokumentation und hält für diese Einsatzgebiete besonders viele Features bereit. Das Tool mag zunächst eher befremdlich und selbst für das Multi-Format-Publishing unnötig kompliziert erscheinen. Die Stärken eines solchen, auf XML aufgesetzten Dokumentensystems mit ausgelagertem, programmierbarem Layout zeigen sich, wenn es ambitioniertere Aufgaben erledigen soll als einfach ein PDF-Dokument schreiben.

Docbook ist äußerst flexibel, so kann ein und dieselbe Masterdatei zum Beispiel auch verschiedene Sprachversionen eines Dokuments enthalten, die sich getrennt generieren lassen (Variantenmanagement). Eine weitere Stärke von Docbook ist mit Sicherheit, dass sich das System besonders für kollaboratives Schreiben eignet. Docbook bietet solchen Projekten einen umfassenden, ausführlich dokumentierten technischen Standard, an dem alle Beteiligten ihre Arbeit orientieren können. Es besteht die Möglichkeit, ein Dokument zu modularisieren und Teildokumente an verschiedene Bearbeiter zu vergeben. Unter eine Versionsverwaltung wie Git oder Subversion gesetzt oder innerhalb einer online aufgesetzten Entwicklungsumgebung lässt sich mit Docbook das Koordinierungschaos vermeiden [2]. Daneben ist Docbook plattformunabhängig.

Docbook wird bei der Organisation OASIS vom Docbook Technical Commitee [3] betreut und steht unter BSD-Lizenz. Für die kommende Release 5.1 gibt es zurzeit zwar schon einen Veröffentlichungskandidaten, aber da 5.0 zum OASIS-Standard wurde [4] empfiehlt sich diese Version für länger angelegte Projekte.

Schemata zum Relaxen

Mit der aktuellen Version 5.0 [5] ist Docbook hauptsächlich in der Schemasprache Relax NG mit einigen Ergänzungen in Schematron implementiert. Die Schemadateien von Docbook [6] installiert der Benutzer auf Debian-basierten Systemen wie Linux Mint oder Ubuntu bequem mit dem Paket »docbook5-xml« . Es enthält zusätzlich alternative Schemata in den Sprachen DTD und XSD, die von OASIS aus Gründen des Komforts zur Verfügung gestellt werden.

Eine restlos konforme Docbook-5.0-Datei ergibt sich allerdings erst, wenn man sie gegen das RNG-Schema validiert. Dabei muss der verwendete Validator auch die Schematron-Ergänzungen berücksichtigen. Für diesen Zweck eignet sich der ursprünglich von Sun Microsystems angebotene Multi-Schema Validator (MSV), der als Zip-Datei erhältlich ist [7]. Nach dem Auspacken ist er mit einem Java Runtime Environment benutzbar. Eine XML-Datei lässt sich folgendermaßen validieren:

java -jar msv.jar /Pfad/rng/5.0/docbook.rng text.xml

Die Prüfung stellt sicher, dass sich die Datei in beliebigen Docbook-Umgebungen, beispielsweise beim Autor und im Verlag, reibungslos verarbeiten lässt.

Editoren

Viele Texteditoren halten für XML grundlegende Features wie Syntax-Highlighting und Wohlgeformtheitsprüfung bereit. Wer aber ambitioniert mit XML arbeitet, nutzt meist einen speziellen XML-Editor, der besondere Funktionen und mehr Komfort bietet. Docbook ist eine der wichtigsten XML-Applikationen, daher gibt es dafür oft Anpassungen.

Der kommerzielle XML-Editor Oxygen [8] besticht als umfangreiche XML-IDE durch seinen ungeheuren Funktionsumfang und bietet auch eine ganze Reihe von besonderen Funktionen für Docbook. Allerdings kostet die proprietäre Software einige Hundert US-Dollar, nur für Bildungseinrichtungen gibt es günstigere Konditionen. XML-Einsteiger erschlägt sie zudem geradezu mit ihrem Funktionsreichtum.

Unter den freien Applikationen bietet zum Beispiel der GPL-lizenzierte XML Copy Editor [9] gegenüber normalen Texteditoren einen großen Mehrwert für XML. Der Anwender kann unter anderem die XSL-Transformationsprozesse bequem vom Editor aus steuern (siehe Linux-Magazin 11/13, [10]).

Der Alleskönner GNU Emacs hält mit seinem XML-Modus NXML kontextsensitive Tag-Vorschläge sowie Echtzeit-Gültigkeitsprüfung gegen Relax-NG-Schemata bereit (Abbildung 1). Für die Docbook-Version 5.0 muss der Anwender aber auch bei aktuellen Emacs-Paketen wie 24.3 zunächst etwas an der Konfiguration basteln [11].

Abbildung 1: Der NXML-Modus von GNU Emacs macht Vorschläge, welche Docbook-Elemente in diesem Kontext passen.

XML als Basis

Docbook ist eine universell konzipierte, sehr umfangreiche XML-Grammatik für die detaillierte Beschreibung verschiedenartiger Dokumententypen in der Druckvorstufe. Für diesen Zweck hält es eine große Anzahl unterschiedlicher Elemente bereit. Schon sich einen Überblick verschaffen ist allerdings mit ansehnlichem Aufwand verbunden. Wer mit Docbook arbeitet, sieht bestimmt oft in die Referenzdokumentation, die auch online angeboten wird [12]. Zusätzlich gibt es umfangreiche, sehr detaillierte Literatur zum Thema Docbook, beispielsweise [13].

Listing 1 zeigt ein einfaches Docbook-5.0-Dokument, eingeleitet mit der obligatorischen XML-1.0-Deklaration. Darauf folgt als Wurzelelement die Dokumentenklasse »<article>« [14]. Docbook 5.0 verwendet man als Standard-Namensraum »xmlns« zusammen mit einem Versions-Attribut. Die Hauptsprache gibt das reservierte XML-Attribut »xml:lang« an. Danach findet sich im Listing ein »<info>« -Metadaten-Container mit »<title>« , dem Personennamen des Autors und seiner E-Mail-Adresse.

01 <?xml version="1.0" encoding="UTF-8"?>
02 <article xmlns="http://docbook.org/ns/docbook" version ="5.0" xml:lang="de">
03 <info>
04 <title>Ein Testartikel</title>
05 <author>
06   <personname>
07     <firstname>Max</firstname>
08     <surname>Mustermann</surname>
09   </Personal>
10   <email>max@maxmustermann.de</email>
11 </author>
12 </info>
13 <section>
14   <title>Markov-Ketten</title>
15   <para>Eine Markow-Kette (engl. Markov chain, auch Markow-Prozess, nach Andrei Andrejewitsch Markow, andere Schreibweisen: <emphasis>Markov-Kette</emphasis>, <emphasis>Markoff-Kette</emphasis>, <emphasis>Markof-Kette</emphasis>) ist ein spezieller stochastischer Prozess<footnote><para>Ein stochastischer Prozess ist die mathematische Beschreibung von zeitlich geordneten, zufälligen Vorgängen.</para></footnote>. Eine Markow-Kette ist darüber definiert, dass [...]
16   </para>
17   <para>Man unterscheidet Markow-Ketten unterschiedlicher Ordnung. [...], während im zeitstetigen Falle die Konzepte der Filtration sowie der bedingten Erwartung benötigt werden.<footnote><para>Quelle: <uri type="website">http://de.wikipedia.org/wiki/Markov-Kette</uri></para></footnote>
18   </para>
19 </section>
20 </article>

Das erste Kapitel »<section>« trägt wiederum einen Titel und enthält mit dem Blockelement »<para>« (Paragraf) mehrere untergeordnete Abschnitte. Innerhalb dieser kommen dann die Inline-Elemente »<emphasis>« , »<footnote>« und »<uri>« zum Einsatz.

Docbook-XSL

Das passend zum XML-Schema entwickelte Docbook-XSL [15] bildet geradezu das Rückgrat von Docbook-Toolchains. Es umfasst eine in XSLT geschriebene Sammlung von Stylesheets, mit denen ein geeigneter Prozessor aus Docbook-XML-Dateien unterschiedliche Zielformate generiert. Mit Docbook-XSL lassen sich Formate wie HTML/XHTML und Linux-Manpages direkt erzeugen, außerdem XSL-FO, das man zu PDF weiterverarbeiten kann.

Bei der aktuellen Version 1.78.1 von Docbook-XSL [16] handelt es sich um XSLT 1.0. Auf Debian-basierten Systemen ist es bequem aus den offiziellen Repositories installierbar, jedoch noch nicht überall in der jüngsten Version. Für Docbook 5.0 greift der Benutzer zum Paket »docbook-xsl-ns« . Die Stylesheet-Releases erhält er auch auf der Projektseite bei Sourceforge [17], die jeweils neueste Entwicklungsversion gibt es als Snapshot.

XSL-FO

Docbook-Stylesheets wendet man mit einem XSLT-Prozessor wie zum Beispiel Saxon an. Eine XSL-FO-Datei produziert der Benutzer damit zum Beispiel mit folgender Kommandozeile:

saxon-xslt -o test.fo test.xml /Pfad/docbook-xsl-ns/fo/docbook.xsl

Es gibt für Saxon spezielle Docbook-Erweiterungen, die auf Debian-Systemen als Paket »docbook-xsl-saxon« installierbar sind. Aus XSL-FO lässt sich etwa mit dem Formatierer Apache FOP eine PDF-Datei herstellen:

fop test.fo test.pdf

Die Silbentrennung in dem resultierenden PDF-Dokument (Abbildung 2) hat übrigens der XSL-FO-Formatierer vorgenommen [18].

Abbildung 2: Mit dem Umweg über XSL-FO entsteht aus Docbook ein PDF-Dokument inklusive Worttrennung.

Bei diesen XSL-Transformationen kommen viele typografische Voreinstellungen zum Tragen, etwa die Seitengröße (standardmäßig US-Letter) oder dass ein Inhaltsverzeichnis generiert wird. Vorgaben wie diese bestimmt der Anwender mit Hilfe einer Reihe von Parametern der XSLT-Stylesheets [19].

Benutzerdefinierte Parameter, etwa das Papierformat, kann er dem Prozessor auch auf der Kommandozeile mitteilen:

saxon-xslt -o test.fo test.xml /Pfad/docbook-xsl-ns/fo/docbook.xsl paper.type="A4"

Alternativ fasst er die Einstellungen in wiederverwendbaren Anpassungsdateien zusammen, den so genannten Zwischenschichten. Diese setzt er dann statt der von Docbook gelieferten XSL-Stylesheets mit dem XSLT-Prozessor ein.

Wie man eine solche Datei aufsetzt, lässt sich aus Listing 2 entnehmen. Zwischenschichten für XSLT-Stylesheets sind selbst XSL(T)-Dateien. An oberster Stelle steht die obligatorische XML-Deklaration. Die einzelnen Operationen sind vom Wurzelelement »<stylesheet>« umschlossen, den Namensraum »xsl« bilden XSLT-Standard-URI und Versionsnummer. Das Element »import« importiert das vom Paket »docbook-xsl-ns« bereitgestellte Stylesheet für die XSL-FO-Ausgabe, die dortigen Parameter kann der Anwender nun einfach überschreiben.

01 <?xml version="1.0" encoding="UTF-8"?>
02 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
03 <xsl:import href="/usr/share/xml/docbook/stylesheet/docbook-xsl-ns/fo/docbook.xsl"/>
04
05 <xsl:param name="paper.type" select="'A4'"/>
06 <xsl:param name="section.autolabel" select="1"/>
07 <xsl:param name="generate.toc" select="0"/>
08 <xsl:param name="fop1.extensions" select="1"/>
09
10 <xsl:attribute-set name="section.title.level1.properties">
11   <xsl:attribute name="font-size">
12     <xsl:value-of select="$body.font.master * 1.5"/>
13   </xsl:attribute>
14 </xsl:attribute-set>
15 </xsl:stylesheet>

Dem Parameter »paper.type« [20] übergibt die Datei den String »A4« . Zudem schaltet sie die Nummerierung der Abschnittstitel (»section.autolabel« ) ein und das Inhaltsverzeichnis (»generate.toc« ) aus, und zwar beides gegen die Voreinstellung. Die »fop1.extensions« sind ein Satz von speziellen Erweiterungen für den FO-Prozessor FOP. Zuletzt stellt das Beispiel die Schriftgröße der Abschnittstitel der ersten Ebene (»section.title.level1.properties« ) auf das 1,5-fache der Brotschrift (»body.font.master« , Voreinstellung: 10 Punkt) um [21].

Latex als Backend

Einen anderen Ansatz zum Erzeugen von PDF-Dokumenten aus Docbook-Quellen verfolgt Dblatex [22]. Anstatt zunächst XSL-FO-Dateien zu erzeugen setzt es auf das Textsatzsystem Latex als Backend. Dblatex (aktuell 0.3.4) ist auf Debian-Systemen und anderen als Paket verfügbar, allerdings ist es von umfangreichen Latex-Paketen abhängig. Der Konverter besitzt viele Optionen, unter anderem lassen sich eigene Latex-Stylefiles einbinden und man kann die Unicode-fähige PDF-Engine Xetex einsetzen.

Neben dem eigentlichen Programm in Python und Latex-Code enthält Dblatex auch eigene XSLT-Stylesheets, um Docbook in Latex-Markup umzuwandeln. Wer hier in die Gestaltung der produzierten PDFs eingreifen möchte oder sich auf Fehlersuche begibt, benötigt aber Detailkenntnisse in Latex.

Konverter

Der universelle Markup-Konverter Pandoc [23] beherrscht zahlreiche Ein- und Ausgabeformate. Seit Version 1.9.3 besitzt er auch einen Reader für Docbook. Auch Pandoc verwendet Latex, um PDFs zu erzeugen, und kennt dabei ähnliche Optionen wie bei Dblatex. Die Konvertierung von Docbook in Latex-Quellcode setzt Pandoc unabhängig von XSL-Transformationen, aber der Benutzer benötigt auch hier Latex-Kenntnisse, um andere als die voreingestellten PDFs zu produzieren. Die aktuelle Pandoc-Version 1.12.1 ist allerdings nur für den OASIS-Standard Docbook 4.5 vorgesehen. Für den robusten Einsatz von aktuellem Docbook ist es daher eher angebracht, Docbook-XSL zu verwenden.

Epub

PDF dient vor allem dazu, gedruckte Dokumente zu präsentieren. E-Book-Formate benötigen dagegen Eigenschaften wie flexible Anpassung des Seitenverhältnisses auf den unterschiedlichen Lesegeräten. Das offene E-Book-Format Epub [24] ist weit verbreitet, und unter der freien Software, mit der man es generieren kann, befindet sich auch Docbook. Bei einer Epub-Datei handelt es sich im Grunde um ein Zip-Archiv, das XHTML-1.0-Dateien neben einem CSS-Stylesheet und einigen Steuerdateien enthält.

Docbook-XSL liefert auch XSLT-Stylesheets für Epub. Im Zusammenspiel mit dem Tool Dbtoepub [25] können Linuxer damit aus Docbook 5.0 mit dem Dokumententyp »<book>« oder »<article>« ein Epub-Dokument herstellen. Dbtoepub ist auf Debian-Systemen als separates Paket erhältlich. Der Konverter lässt sich einfach auf der Kommandozeile nutzen:

dbtoepub -o test.epub test.xml

Abbildung 3 zeigt das Ergebnis. Mit der Option »-c« bindet der Benutzer eigene CSS-Stylesheets ein, um das resultierende Epub-Dokument typografisch zu manipulieren, mit »-f« lassen sich dabei auch beliebige Open-Type-Schriften einsetzen.

Abbildung 3: Das Docbook-5.0-Beispiel als Epub-Dokument im freien E-Book-Leseprogramm Fbreader.

Dbtoepub erlaubt es außerdem, mit dem Schalter »-s« beliebige XSLT-Stylesheets oder Zwischenschichten bei der Umwandlung zu berücksichtigen. Docbook-XSL hat allerdings einen gewissen Rückstand bei der Dokumentation von Epub, sodass der Benutzer gegebenenfalls die verfügbaren Parameter direkt in der Stylesheet-Datei »docbook-xsl-ns/epub/docbook.xsl« nachsehen muss.

Fazit

Docbook ist ein flexibles, professionelles Publishingsystem. Es ist sehr weit entwickelt, und im Zusammenspiel mit verschiedenen XML-Werkzeugen lässt sich damit eine produktive Verarbeitungsumgebung für hochwertige Druckerzeugnissen und elektronische Dokumente aufsetzen. Deshalb erfreut es sich auch weiter Verbreitung. Zu den Anwendern gehören große Open-Source-Projekte wie Gnome und KDE, IT-Unternehmen wie Suse und Rackspace sowie Verlage wie beispielsweise O’Reilly [26].