Kapitel 2. Erstellung von DocBook-Dokumenten

Dokumentationen mit DocBook-XML

Kapitel 2. Erstellung von DocBook-Dokumenten

Beispielkonfiguration. Zum Testen der in diesem Kapitel durchgeführten Beispiele empfehle ich folgende Software. Für Beispiele wird der entsprechende Code einerseits in der Quell-Version angegeben, zum anderen anhand des fertigen Dokuments nachvollziehbar gemacht.

Empfohlene Software

Dokumenttypen

DocBook unterscheidet als Dokumenttypen article, book und set. Ein article ist geeignet für kurze Artikel, Whitepapers, Technische Notizen, FAQs aber auch Zeitschriftenartikel. Größeren Dokumente, also Büchern, Handbüchern, Nachschlagewerken, Bedienungsanleitungen und so weiter wird am besten mit dem Dokumententyp book entsprochen. Für Sammlungen von Büchern bietet sich der Dokumenttyp set an. Ein gutes Beispiel ist die Sammlung aller Dokumente, die bei der Erstellung einer Software anfallen.

Anmerkung

Für kurze Dokumente article, für lange book

In den folgenden Abschnitten werde ich diese drei Dokumenttypen vorstellen, auf ihre einzelnen Bestandteile gehe ich in dem Abschnitt Dokumentteile detaillierter ein.

Erstellung eines Buches

Der Dokumententyp book besteht mindestens aus einem Titel (title) oder einem Satz an Informationen über das Buch (bookinfo) und dann einer beliebig langen Reihe von Buchbestandteilen wie Inhaltsverzeichnissen (toc), Vorworten (preface), Kapiteln (chapter), Glossars (glossary), Stichwortverzeichnissen (index) und Anhängen (appendix). Diese Elemente sind alle optional, aber der Titel oder die Buchinformationen müssen enthalten sein.

Beispiel 2.1. Ein sehr kurzes Buch

<?xml version='1.0' encoding='UTF-8'?> 
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book lang="de"> 
	<title>
		Kürzer geht es nicht</title> 
</book>

Sprache definieren. Beachten Sie in dem vorhergehenden Beispiel, dass den Element book der Parameter lang mit dem Wert „de“ zugeordnet wurde. Dieser Parameter ist ein Universalattribut und kann in jedem Element auftauchen. In diesem Fall bedeutet es, dass das Buch in deutscher Sprache verfasst ist. Dies ist insbesondere geeignet, um fremdsprachige Teile in einem Dokument zu markieren.

Anmerkung

Die Festlegung der Sprache ist wichtig, um automatisch generierte Texte verwenden zu können

Beispiel 2.2. Ein etwas längeres Buch

<?xml version='1.0' encoding='UTF-8'?> 
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book lang="de"> 
	<bookinfo>
		<title>
			Es geht noch kürzer
		</title>
	</bookinfo> 
	<chapter>
		<title>
			Das erste und einzige Kapitel
		</title> 
		<para>
			Dieses Kapitel ist sehr kurz. 
		</para> 
	</chapter> 
</book>

Wenn wir in diesem Beispiel nur den oberen Teil des Dokuments betrachten und den Teil um das einziger chapter außer Acht lassen, dann wird deutlich, dass dieses Dokument ebenfalls den Anforderungen an ein DocBook-Buch genügt.

1

In dieser Zeile erscheint anstatt des Titels das Element, welches sämtliche Metainformationen des Buchs halten kann.

2

Jedoch enthält dieses wiederum einen title, der sich jedoch auf das gesamte book bezieht. Damit ist das Buch nicht ohne Bezeichnung und das Dokument ist gültig.

Eine weitere Besonderheit des book-Elements ist es, dass es sowohl Artikel als auch Teile (part), die wiederum Kapitel enthalten können.

Anmerkung

book kann part enthalten.

Erstellung eines Artikels

Die Erstellung eines Artikels (article) verläuft analog zu Erstellung eines Buches mit dem Unterschied, dass das Element, welches die Meta-Informationen hält, jetzt articleinfo heißt und dass ein Artikel keine Kapitel enthält, aber Inhaltsverzeichnisse, Anhänge, Stichwortverzeichnisse und ähnliches enthalten kann.

Anmerkung

article dürfen keine chapter haben

Eine weitere Besonderheit des article ist es, dass er das Attribut class tragen kann, welches angibt, um welche Art von Dokument es sich handelt. Mögliche Dokumentarten sind: faq, journalarticle, productsheet, specification, techreport, whitepaper, .

Beispiel 2.3. Ein sehr kurzer Artikel

<?xml version='1.0' encoding='UTF-8'?> 
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article lang="en"> 
	<title>
		A very short article
	</title> 
</article>

Erstellung einer Sammlung

Eine Sammlung (set) besteht im wesentlichen aus einer Reihe von Büchern (book). Jedes set muss einen Titel oder ein setinfo haben und darf ein globales Inhaltsverzeichnis (toc) und eine globale Stichwortliste (setindex) haben. Eine Sammlung, die weniger als ein Buch enthält, kann kein gültiges Dokument bilden.

Beispiel 2.4. Eine Sammlung zweier Bücher

<?xml version='1.0' encoding='UTF-8'?> 
<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<set>
  <book lang="de"> 
	  <bookinfo>
		  <title>
			  Es geht noch kürzer
		  </title>
	  </bookinfo> 
	  <chapter>
		  <title>
			  Das erste und einzige Kapitel
		  </title> 
		  <para>
			  Dieses Kapitel ist sehr kurz. 
		  </para> 
	  </chapter> 
  </book>
  <book lang="en"> 
  	<title>
  		This is very short</title> 
  </book>
</set>

Das Beispiel zeigt noch einmal, dass unterschiedliche Elemente eines Dokuments in unterschiedlichen Sprache verfasst sein können.