[http://www.docbook.org/ DocBook] ([Wikipedia DocBook|http://en.wikipedia.org/wiki/DocBook]) ist eine XML-Beschreibungssprache für Dokumente. Es ist gut geeignet, um aus einem Quell-(DocBook-)Dokument verschiedene Ausgaben, z.B. als HTML, PDF oder EPub zu erzeugen. Um das zu erreichen, wird der Text in DocBook lediglich in Tags eingeschlossen, die die Bedeutung des Textes innerhalb des Dokumentes markieren. Konkrete Formatierungen sind nicht nötig (und auch nicht möglich), weil diese dem entsprechenden Umwandler in das Zielformat unterliegen.

Um sich in das Format einzuarbeiten, sollte man zuerst einmal [http://www.docbook.org/tdg5/ DocBook - The Definitive Guide] lesen.


== Editoren ==

Letztlich ist DocBook XML und kann daher leicht mit jedem Texteditor geschrieben werden. Die besten Ergebnisse erreicht man jedoch mit einem guten XML-Editor. Ist man jedoch auf der Suche nach einem WYSIWYG-Editor und möchte dann womöglich noch freie Software einsetzen, wird die Luft aber dann doch irgendwann dünn. Es gibt in der Wikipedia eine [http://en.wikipedia.org/wiki/Comparison_of_XML_editors Vergleichsliste von XML-Editoren].

* [http://wiki.eclipse.org/Vex Vex] scheint das einzige echte und lebende freie Projekt eines XML WYSIWYG-Editors zu sein, der gut mit DocBook umgehen kann.
* [http://plugins.jedit.org/plugins/?XML JEdit mit XML-Plugin] kann zwar kein WYSIWYG, ist aber ein Editor für Programmierer, den man auch im Auge behalten sollte. Wenn ich nicht inzwischen fast alles nur noch in Exlipse machen würde, würde ich diesen Editor lieben.
* [http://de.sourceforge.net/project/serna-free/ Serna Free] ist ein sehr schöner WYSIWYG-Editor, mit dem man auch Laien zeigen kann, wie sie DocBook-Dokumente erzeugen können. Um DocBook 5.x zu verarbeiten, gibt es [einen Trick|https://wiki.hpdd.intel.com/display/PUB/Making+changes+to+the+Lustre+Manual+source#MakingchangestotheLustreManualsource-serna], den man wissen sollte: Man kann die 4.5-Schablone verwenden und ändert das verwendete Schema ab.


== Validieren ==

Wer möchte, kann eine DocBook-Datei validieren, d.h. prüfen, ob diese eine gültige Datei ist und alle Elemente richtig verwendet wurden.

Im DocBook-Buch wird als Tool zum Validieren auf der Kommandozeile "Sun MSV" empfohlen. Das bekommt man eigentlich unter https://msv.java.net/. Leider hat wohl die Projektseite (wie so viele) unter dem Umzug von java.net nach der Oracle-Übernahme arg gelitten. Daher ist wohl das Wiki und die Dokumentation weg und die neueren jar-Files ergaben für mich kein lauffähiges Programm (sondern nur Bibliotheken). Allerdings bekommt man unter "older Downloads" eine Version von 2009, die für die Beispiele aus dem Buch wunderbar funktioniert.


== Versionen ==

Es gibt von DocBook die ältere Version bis 4.5 und das neuere (seit 2010) 5.0. Die Unterschiede sind relativ bedeutetend, weil einige Änderungen nicht ganz abwärtskompatibel waren. Insbesondere wird auch zum Validieren eine andere Stylesheet-Sprache benutzt. Bei der Recherche im Internet sollte man darauf achten, welche Version jeweils besprochen wird.


== Dokumentation ==

Wichtig sind zwei Bücher, die auch Online zu lesen sind. [DocBook 5: The Definitive Guide|http://www.docbook.org/tdg5/en/html/docbook.html] ist die Beschreibung der DocBook-Elemente. Es besteht aus einer guten Einführung und einer sehr ausführlichen Referenz zu jedem einzelnen XML-Element. Die Beschreibung der Elementeigenschaften ist aber jeweils immer recht allgemein gehalten und unabhängig vom Ausgabeformat, das man haben möchte. Das zweite Buch, [DocBook XSL: The Complete Guide|http://sagehill.net/docbookxsl/index.html] beschreibt nun die XSL Dateien, die dazu dienen, bestimmte Ausgabeformate zu erzeugen und geht auf die Einstellungen und Anpassungen ein, die man dort vornehmen kann.


== Erzeugen von PDFs ==

Auf meinem Debian-System habe ich mit folgenden Befehlen ein PDF aus einer DocBook-Datei erzeugt und angezeigt.

  saxon-xslt -o Buch.fo Buch.docbook /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/fo/docbook.xsl
  fop Buch.fo Buch.pdf
  evince Buch.pdf

Für die erste Zeile geht auch alternativ:

  xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/fo/docbook.xsl Buch.docbook >Buch.fo

Man kann also für den ersten Schritt einen beliebigen XSLT-Generator nehmen. Einige Anleitungen verwenden xsltproc (in C, schneller als saxon) und einige empfehlen Saxon (in Java, Plattformunabhängiger und manche sagen, es sei besser bei bestimmten Elementen). Einige empfehlen auch das ältere Openjade. Ich kann bisher nur sagen, das xsltproc und Saxon für mich lief (und ersteres wirklich signifikant schneller ist).

Eine Alternative könnte übrigens auch [http://dblatex.sourceforge.net/ dblatex] sein. Ich habe es noch nicht ausprobiert, habe aber Zweifel, ob es schon DocBook 5 verwendet. Dafür erzeugt es die Ausgabe per Latex, was sicherlich eine attraktive Ausgabe ergeben kann und für erfahrene Latex-Hacker bestimmt zusätzliche Reize hat.


== Debian-Pakete ==

Die folgenden Pakete benutze ich zur Arbeit mit DocBook 5.0. Leider bin ich nicht nach einigen Versuchen gar nicht mehr hundertprozentig sicher, was ich alles installiert und deinstalliert habe. Vielleicht verbessert oder bestätigt der nächste ja die folgende Paketliste:

  docbook5-xml
  docbook-xsl-ns
  docbook-xsl-saxon und/oder xsltproc

  
== Einführungen, Anleitungen und Links ==

* [Pro-Linux|http://www.pro-linux.de/artikel/2/1622/einfuehrung-in-docbook.html] bzw. [freiesmagazin.de|http://www.freiesmagazin.de/mobil/freiesMagazin-2013-03-bilder.html#fm_13_03_einfuehrung_docbook] Artikel aus 2013 über DocBook 5.0 unter Debian (deutsch)
* [http://www.vogella.com/tutorials/DocBook/article.html Lars Vogel (vogella.com)] hat auch zu diesem Thema bereits gearbeitet und einen Artikel über die Arbeit mit DocBook in Eclipse (u.a. mit Vex) geschrieben.
* [IBM Developerworks|http://www.ibm.com/developerworks/library/os-eclipse-docbook/index.html?ca=drs] hat auch einen Artikel zu DocBook in Eclipse
* [http://dep4e.sourceforge.net/ DEP4E] ist ein Projekt, um DocBook-Komponenten in Eclipse einzubinden. Ich habe es noch nicht ausprobiert, es scheint aber bis auf den WYSIWIG-Editor alles da zu sein.
* http://doccookbook.sourceforge.net/html/en/ Cookbook mit vielen guten Tips (benutzt DocBook 5.0, ist also relativ aktuell)