Open Source im professionellen Einsatz
Linux-Magazin 02/2014
© pixpack, 123RF.com

© pixpack, 123RF.com

Multi-Format-Publishing mit Docbook

Doku-Maschine

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.

517

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.

Diesen Artikel als PDF kaufen

Express-Kauf als PDF

Umfang: 4 Heftseiten

Preis € 0,99
(inkl. 19% MwSt.)

Linux-Magazin kaufen

Einzelne Ausgabe
 
Abonnements
 
TABLET & SMARTPHONE APPS
Bald erhältlich
Get it on Google Play

Deutschland

Ähnliche Artikel

  • WTFM!

    Die letzte Zeile Code ist geschrieben, das Makefile übersetzt das eigene Softwarepaket. Doch halt! Die Dokumentation fehlt! Nur wenige Entwickler mögen das einige Jahrzehnte alte Troff-Format, in dem Manpages formuliert sind. Docbook beendet die Schreibblockade.

  • Bitparade

    Zu guter Software gehört ausführliche Dokumentation. Wer keine Angst vor Quelltext hat, greift zum Format Docbook-XML, aus dem sich von der Manpage bis zum E-Book allerlei generieren lässt. Mit den offenen Publishing-Systemen Daps, Publican und Yelp bekommt ein Autor auch dicke Handbücher in den Griff.

  • Epub-Tools

    Wer E-Books im verbreiteten Epub-Format erzeugen möchte, findet in der Open-Source-Werkzeugkiste reichlich Unterstützung – ob per GUI-Anwendung, Office-Erweiterung oder Kommandozeile sowie mit und ohne XML/XSLT-Kenntnisse. Als Eingabeformate eignen sich ODT, Docbook oder Latex.

  • Wider den Wildwuchs

    Wer in einem Team an Softwaredokumentationen arbeitet und dabei etwa Open-Office-Dokumente per E-Mail austauscht, der handelt sich leicht Probleme ein, wenn sich Änderungen überschneiden oder die Mitstreiter Formate uneinheitlich gebrauchen. Doch es gibt einen besseren Weg.

  • Seiten-Aufbau

    XML und XSL-Stylesheets sind die Mittel der Wahl, um auf Webseiten Inhalt und Layout sauber getrennt zu halten. Das Framework Website-DTD hilft dabei.

comments powered by Disqus

Ausgabe 07/2017

Digitale Ausgabe: Preis € 6,40
(inkl. 19% MwSt.)

Artikelserien und interessante Workshops aus dem Magazin können Sie hier als Bundle erwerben.