Open Source im professionellen Einsatz
Linux-Magazin 12/2015
© Bryan Fickett, 123RF

© Bryan Fickett, 123RF

Publishing-Systeme für Docbook-XML

Kluges aus der Quelle

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.

362

Dokumentation für das durchschnittliche Softwaretool lässt sich bereits mit einfachsten Mitteln verfassen. Ein Readme für ein kleines Open-Source-Programm ist beispielsweise mit einem beliebigen Texteditor schnell geschrieben und liegt daher auch den meisten Quelltextpaketen bei. In den letzten Jahren greifen Entwickler für solche Dokumente gern auch zum Markdown-Format [1], das der Codehoster Github automatisch ansehnlich formatiert. Es beherrscht Aufzählungen, Listings und Weblinks.

Dicke Handbücher

Die Anwender leistungsfähiger Softwaresuites benötigen und erwarten hingegen deutlich umfangreichere Dokumente, sprich: richtige Handbücher. Das gilt insbesondere dann, wenn hinter der freien Software ein Unternehmen steht, das die Software auch in einer kostenpflichtigen Version mit Subskription und Support anbietet.

In dieser Liga spielt das Format Docbook [2], das in einer SGML- und XML-Ausprägung existiert. Damit trotzt es der Kritik, es sei zu wortreich und überladen, und behauptet sich auch gegenüber leichtgewichtigeren Konkurrenten wie etwa Restructured Text [3]. Von Inhalts- und Abbildungsverzeichnissen über Querverweise bis hin zum Index sieht es alles vor, was ein Entwickler für ein professionelles Handbuch benötigt.

Daneben hat es sich als eine Art Verkehrssprache der technischen Dokumentation etabliert. Freie Software kommt mit dieser Sprache ebenso zurecht wie proprietäre Anwendungen, beispielsweise Adobes Framemaker. Wer auf Docbook-XML setzt, muss sich keine Sorgen darum machen, ob er seine Dokumente auch in wenigen Jahren noch lesen und pflegen kann. Allerdings darf er keine Scheu vor der Arbeit mit XML-Quelltext haben, die er sich aber durch die Wahl eines geeigneten Editors erleichtert.

Bereits an Bord

Die Docbook-Schemata und eine Sammlung von XSL-Stylesheets zum Umwandeln in HTML und weitere Formate gehören zum Paketumfang praktisch jeder Linux-Distribution. Damit lässt sich Single-Source-Publishing verwirklichen, also das Erzeugen von Man-, Info-, HTML-, PDF- und Epub-Dokumenten aus demselben Quelltext. Ein Artikel im Linux-Magazin 02/14 [4] beschreibt, was sich mit Docbook alles anstellen lässt.

Ein praxistaugliches Publishing-System muss aber noch mehr bieten – insbesondere wenn mehrere Benutzer damit arbeiten sollen: Es sollte vorgeben, wo die zahlreichen XML-, Bild- und sonstigen Dateien eines Dokumentationsprojekts landen, den Build der Ausgabedateien automatisieren sowie sicherstellen, dass die Querverweise nicht ins Leere zeigen. Daneben sollte es in einem Rutsch das Gerüst für ein neues Dokumentationsprojekt anlegen, was insbesondere Einsteigern hilft.

Diesen Artikel als PDF kaufen

Express-Kauf als PDF

Umfang: 5 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

  • Gnome 3.0 erhält überarbeitete Doku

    Das Gnome-Dokumentationsteam strukturiert Handbuch und Hilfedateien für die kommende Version der 3.0 der Desktopumgebung gründlich um.

  • Docbook

    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.

  • 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.

  • Wayland und Weston erreichen Version 1.7.0

    Für Wayland gibt es Änderungen an der Testsuite und der Dokumentation und was die Entwickler mit Weston vorhaben, wissen sie nun auch ungefähr.

  • Txt2tags 2.6 produziert Asciidoc und Docbook

    Das GPL-lizenzierte Konvertierungstool Txt2tags beherrscht in Version 2.6 neue Ausgabeformate.

comments powered by Disqus

Ausgabe 09/2017

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