Dokumentenformate im Vergleich DocBook, ASCIIDoc oder Sphinx?

Welches sind die Eigenschaften und die Nachteile der am häufigsten genutzten Dokumentenformate beziehungsweise Auszeichnungssprachen für das Erstellen von Artikeln und technischen Dokumentation? Der Artikel bringt einen Vergleich von DocBook, ASCIIDoc und Sphinx.

Jeder, der schon einmal eine Bedienungsanleitung oder dergleichen benutzt hat, weiß, wie wichtig es ist, auf genaue Anleitungen und Erklärungen für die unterschiedlichen Produkte zurückgreifen zu können. Da Dokumentation – vor allem in der Software-Welt - unumgänglich ist, gibt es eine Menge an Tools, die – je nach Vorliebe der Autoren - zur Erstellung von Dokumentationstexten eingesetzt werden können.

Eine erste Übersicht findet sich in folgender Tabelle.

Die Einträge entsprechen der Reihenfolge im Artikel.

Die Funktionsweise

Die grundsätzliche Funktionsweise der jeweiligen Dokumentenformate stellen sie wie folgt dar:

• ASCIIDoc ist eine vereinfachte Auszeichnungssprache und basiert auf Plain Text. Dateien können nach HTML und DocBook konvertiert werden und von dort aus in weitere Ausgabeformate. ASCIIDoc kann mit pandoc oder ASCIIDoc Befehlen konvertiert werden. Das Konvertierprogramm, dass hierfür genutzt wird (asciidoc), wurde in Python geschrieben.

• DocBook ist ein Dokumentenformat auf Basis von XML. Zuerst wird das Format strukturell überprüft („Validierung“) und danach über DocBook-XSL-Stylesheets in ein Zielformat (HTML, Text, Manpage, …) überführt. Wird PDF gewünscht, wird zuerst in ein Zwischenformat überführt, das mit Hilfe des Tools FOP in PDF umgewandelt wird.
  Das Suse-Dokumentationsteam zum Beispiel nutzt zur Konvertierung von Texten in verschiedene Dateiformate für DocBook das selbstentwickelte Programm „DocBook Authoring and Publishing Suite“, (DAPS). DAPS wurde unter der GNU Public License veröffentlicht und steht somit anderen Unternehmen zur freien Nutzung zur Verfügung.

• Sphinx ist eine Software, die die vereinfachte Auszeichnungssprache reStructuredText (reST) nutzt, um damit letztendlich Formate wie PDF erzeugen zu können. Zur Konvertierung von Texten in verschiedene Dateiformate greifen Autoren auf Sphinx-spezifische Befehle zurück. Die Erweiterbarkeit und die Funktionen zur syntaktischen Analyse und das Übersetzungssystem der DocUtils, die reST beinhalten, spielen bei Sphinx eine wichtige Rolle.

Um die Semantik der drei zu vergleichenden Formate zu verstehen, gibt es einfache Merksätze, die recht gut beschreiben, wie der geschriebene Text zu interpretieren ist:

GitHub

Ein heute wichtiges Merkmal ist die Möglichkeit der Online-Bearbeitung von Textdateien in GitHub. Alle Dokumentenformate und -Sprachen werden hier unterstützt, jedoch in verschiedenen Ansichten.

DocBook zum Beispiel kann in GitHub nur als farbiger XML-Quellcode angesehen werden, was die Lesbarkeit für einige Entwickler schwierig macht. ASCIIDoc und Sphinx hingegen sind als Format bereits leicht lesbar und werden in GitHub sogar als gerendertes HTML angezeigt. Die Internet-Browser Firefox, Opera und Chrome bieten zudem Erweiterungen an, die es ermöglichen ASCIIDoc zu bearbeiten.

Die Editoren

Außerhalb von GitHub ist die Nutzung eines Texteditors üblich. Im Prinzip lässt sich jeder Texteditor nutzen, jedoch bieten sich folgende Editoren für die speziellen Dokumentenformate an.

Die entsprechenden Formate werden durch die angegebenen Editoren unter anderem durch Highlighting, durch Erweiterungsfunktionen, durch das Setzen von Makros und durch Vorschauoptionen unterstützt.

DocBook hat hier eine Sonderrolle inne: Durch die XML-Struktur lässt sich das Format mit einem so genannten „Schema“ verknüpfen. Kann ein Editor dieses Schema nutzen, zeigt der Editor Vorschläge an. Durch diese Vorschläge kann der Benutzer die gültigen Tags kontextsensitiv auswählen.

Die Erweiterungsmöglichkeiten

Damit die Sprachen variabel und individuell genutzt werden können sind Erweiterungen nützlich. Erweiterungen können das Format selbst erweitern oder bei der Umwandlung eingreifen.

ASCIIDoc beinhaltet selbst vier offizielle Erweiterungen, und zudem sind eine Menge Erweiterungen von Drittanbietern erhältlich.

Sphinx hat ebenfalls einige eigene Erweiterungsoptionen, darunter zum Beispiel „imgmath“ und „doctest“. Aber auch für Sphinx gibt es noch zusätzliche Erweiterungen von Drittanbietern.

Eine andere Form der individuellen Anpassung der Dokumentenformate ist nur in DocBook gegeben. Hier lässt sich klar definieren, welche Tags in welchen Kombinationen verwendet werden dürfen, welche Tiefe und Anzahl von Subtags jeder Tag haben darf, und welche Tags für ein Dokument überhaupt genutzt werden dürfen.

Die Platzhalter

Platzhalter sind für viele Technische Redakteure und Dokumentationsentwickler eine große Hilfe, da sie Standards festlegen können und deren Nutzung den Schreibprozess vereinfacht. Diese Möglichkeit ist in alle Dokumentenformaten, die hier verglichen werden, gegeben.

DocBook nutzt hierfür Entity-Definitionen (meistens abgelegt in eigenen .ent-Dateien). ASCIIDoc nutzt textinterne „References“ und Sphinx arbeitet mit Substitutionen und „ref_epilog“ Dateien.

Die Varianten

In manchen Fällen wird Dokumentation für verschiedene Varianten benötigt, die nur kleine Unterschiede enthalten. Beispielsweise gibt es verschiedene Produkte mit verschiedenen Namen, welche unterschiedlich installiert werden, die Nutzung jedoch ist bei allen gleich.

Für diese Fälle werden alle möglichen Varianten im Dokument integriert und durch „Marker“ voneinander abgegrenzt. Das ist sowohl bei DocBook über Attribute, als auch bei ASCIIDoc mit „ifdef“ und „enddef“ Attribut-Funktionen, und bei Sphinx mit „SET profiling“ IDs möglich.

Die Modularisierung

Wichtig bei komplexeren Dokumentationen, die viele verschiedene Artikel und Bücher umfassen, ist die Modularisierung. Alle hier verglichenen Dokumentenformate bieten diese Möglichkeit über „includes“ an.

Die Validierung

Damit überprüft werden kann, ob die Dokumentation im jeweiligen Format zulässig ist und keine formalen Fehler enthält, also valide ist, ist eine regelmäßige und abschließende Validierung notwendig.

DocBook (XML) Texte lassen sich leicht in unterstützenden (XML-)Editoren oder über eine DAPS-Funktion (daps --validate) validieren, indem die Struktur des Dokuments anhand eines Schemas (eine Art „Blaupause“) abgeglichen wird.

Bei ASCIIDoc und Sphinx ist eine Validierung im Sinne und der Strenge von DocBook nicht vorgesehen. Bei beiden genannten Formaten wird lediglich die Syntax überprüft, eine strukturelle Validierung wie in DocBook ist nicht möglich.

Die ASCIIDoc Validierung ist nur bedingt über einige wenige Editoren und den W3C Kommandozeilen Validator möglich. Sphinx Dokumentationen lassen sich über eine interne Erweiterung validieren.

Die Ausgabe

Die jeweiligen Dokumentenformate unterstützen teilweise die gleichen, teilweise unterschiedliche Datei- beziehungsweise Ausgabeformate.

Üblicherweise werden heutzutage Markup (Text) und Layout (Gestaltung) voneinander getrennt damit sie unabhängig voneinander implementiert werden können. Dadurch können sich Redakteure ganz auf ihren Text konzentrieren und müssen sich nicht um die Gestaltung kümmern.

DocBook stellt für die Gestaltung Stylesheets zur Verfügung, es können jedoch auch eigene Stylesheets angelegt oder vorhandene individualisiert werden. ASCIIDoc nutzt die DocBook Stylesheets, daher ist eine Bearbeitung hier ebenfalls möglich. In beiden Fällen sind jedoch XSLT-Kenntnisse notwendig. Sphinx liefert sogenannte „Designvorlagen“ (engl. „themes“), aber auch hier können individuelle Vorlagen erstellt und hinzugefügt werden.

Stärken und Schwächen der verschiedenen Formate

DocBooks Schwäche liegt vor allem - solange keine individuellen Einstellungen und Limitierungen vorliegen - bei den Tags. Die Anzahl der Tags, ihre Kombinationsmöglichkeiten und die Anforderungen der verschiedenen Tags können verwirrend sein.

Daher dauert das Erlernen dieses Dokumentenformates länger als bei ASCIIDoc oder Sphinx. Zudem ist XML nicht besonders gut lesbar, sodass XML-Laien dabei Schwierigkeiten haben könnten und Feedback kompliziert ist. Außerdem sollten Nutzer DocBook nur verwenden, wenn ein XML-unterstützenden Editor genutzt werden kann.

Die Problematik von ASCIIDoc liegt vor allem in der fehlenden direkte Ausgabe von PDF: diese ist nur über den Umweg über DocBook möglich. Auch für diese Auszeichnungssprache ist ein unterstützender Editor wichtig, da die Textidentifizierer zwingend Highlighting benötigen, um eine klare Übersicht über den Code zu behalten.

Dasselbe gilt für Sphinx. Eine große Schwäche von Sphinx ist vor allem, dass es schwierig ist Fehler ausfindig zu machen. Zudem lässt sich Sphinx im Gegensatz zu DocBook und ASCIIDoc weniger leicht erweitern und ist nicht so flexibel in seinen Funktionen.

Allerdings hat auch jedes dieser Formate seine Stärken. DocBook ermöglicht zum Beispiel einen einfachen Import von anderen Dateiformaten, eine hohe Portabilität und besitzt außerdem eine hohe und flexible Erweiterbarkeit. Zudem lassen sich Texte über ein Schema strukturell validieren.

ASCIIDoc hat seine Stärken vor allem in der guten Lesbarkeit des Codes und dem einfachen Setup. Die Lesbarkeit von Sphinx (reST) ist ebenfalls ein Pluspunkt, außerdem ist die gute HTML Ausgabe mit integrierter Schnellsuchleiste eine echte Stärke.

Die Empfehlung

Wenn ein leicht individualisierbares Dokumentenformat mit flexibler Erweiterbarkeit und Unterstützung für umfassende und komplexe Dokumentation gebraucht wird, dann ist DocBook mit Sicherheit die beste Wahl. Steht jedoch eine enge Zusammenarbeit mit Entwicklern im Vordergrund, für die das Format direkt lesbar sein soll, sind ASCIIDoc und Sphinx besser geeignet.

* Janina Setz macht seit dem 1. September 2016 bei Suse eine Ausbildung zur Fachinformatikerin. Die Entstehung des Artikels hat Meike Chabowski, Documentation Strategist bei Suse, begleitet.

(ID:44733518)