Einführung in Docbook

Hello, world!

Das XML einer Docbook-Datei lässt sich grundsätzlich mit jedem beliebigen Texteditor schreiben und bearbeiten. Eine rudimentäre Docbook-Datei sieht nun folgendermaßen aus:

<?xml version="1.0" encoding="UTF-8"?>
<article version="5.0" xmlns="http://docbook.org/ns/docbook">
    <title>Testdokument</title>
    <para>Hello, world!</para>
</article>

In der ersten Zeile steht die für XML übliche Standard-Deklaration, welche die Datei als XML-Dokument ausweist und die Textcodierung festlegt. Docbook 5.x hingegen wird in Betrieb genommen, indem man für eines der gültigen Wurzelelemente davon (hier: article) die gewünschte Versionsnummer und die für Docbook 5.x vorgesehene URI als Standard-Namensraum festlegt.

Eine Datei foo.xml (gebräuchlich ist auch die Dateiendung .dbk für Docbook-Dateien) wie diese lässt sich nun gegenüber dem Docbook-Schema validieren, zum Beispiel mit xmllint aus dem Paket libxml2-utils:

xmllint --relaxng /usr/share/xml/docbook/schema/rng/5.0/docbook.rng foo.xml

OASIS empfiehlt im Docbook-Howto dafür allerdings den Multi-Schema XML Validator (MSV) von Sun, der in Java implementiert ist:

java -jar ~/Downloads/msv/msv.jar /usr/share/xml/docbook/schema/rng/5.0/docbook.rng foo.xml

Sollen modulare Dokumente benutzt werden, bei denen Teilstücke in die Masterdatei mittels XInclude eingefügt werden, so muss gegenüber den Schemata docbookxi.rng/.rnc validiert werden, die sich auch in docbook/rng/5.0 befinden. Aus einem syntaktisch und strukturell fehlerfreien, d.h. wohlgeformten und gültigen Docbook-Dokument können dann in einem weiteren Schritt mit gängigen XML-Tools verschiedene Ausgabeformate hergestellt werden (siehe weiter unten).

Docbook-Elemente

Docbook 5.0 beschreibt 385 verschiedene Elemente mit entsprechenden Tags, die im Verhältnis zu anderen Elementen im Sinne der Baumstruktur von XML auf unterschiedlichen hierarchischen Ebenen angesiedelt sind. Neben den reinen Steuerungselementen sind diese in die Gruppen Strukturelemente, Blockelemente und Inline-Elemente zusammengefasst.

Von den Strukturelementen sind zunächst die Wurzelelemente <set> und <book> (ein <set> enthält mehrere <book>s) zu nennen. Ein Buch (<book>) enthält zunächst einen <info>-Abschnitt, der den Buchtitel trägt und unter anderem den Autorennamen beinhaltet. Es kann mit verschiedenen Komponenten ausgestattet werden, wie z.B. einer Widmung (<dedication>), einem Vorwort (<preface>) und verschiedenen Dingen wie einem Inhaltsverzeichnis (<toc>), Indices (<index>) oder einem Glossar (<glossary>). Es besteht aber vor allem natürlich aus Artikeln (<article>) oder Kapiteln (<chapter>), die Textabschnitte (<para>) enthalten, welche wiederum in verschiedene Abschnitte (u.a. <section>) unterteilt sein können. Blockelemente sind nun diejenigen Elemente, die auf der Ebene von angewendet werden können. Es handelt sich dabei z.B. um Listen, Tabellen und Blockzitate. Die z.B. aus den Büchern von O'Reilly bekannten separaten Hinweise (admonitions) gehören auch hierzu (<caution>, <important>, <tip>). Die Inline-Elemente schließlich sind diejenigen, die im laufenden Text Verwendung finden. Es handelt sich hierbei zum Beispiel um <emphasis>, Abkürzungen, Fußnoten, und Querverweise. Da Docbook aus der Software-Dokumentation stammt, finden sich für diesen Zweck besonders viele nützliche Elemente.

Ein <article> kann, wie oben gesehen, auch auch als selbständiges Wurzelelement verwendet werden und kann – ähnlich wie ein Buch – mit verschiedenen Komponenten wie einem Inhaltsverzeichnis, Indices, Glossaren usw. ausgestattet werden. Die Datei docbook_test.xml (aus Gründen der Übersichtlichkeit nur verlinkt) zeigt gegenüber dem obigen »Hello, world!«-Beispiel ein mit Info-Block und verschiedenen Abschnitten versehenes, aufwändigeres Beispiel.