Kapitel 2. Erstellung von DocBook-Dokumenten

Inhaltsverzeichnis

Dokumenttypen
Erstellung eines Buches
Erstellung eines Artikels
Erstellung einer Sammlung
Dokumentteile
Widmung
Navigationskomponenten
Inhaltsverzeichnisse
Ressourcenverzeichnisse
Stichwortverzeichnisse
Komponenten
Vorworte, Kapitel und Anhänge
Erstellung eines Literaturverzeichnisses
Abschnitte
Typische Absatzelemente
Absätze
Listen
Angestrichene Listen
Geordnete Listen
Unterteilte Listen
Variablenlisten
Anmerkungen
Beispiele und Abbildungen
Beispiele
Grafiken und Medien
Abbildungen
Tabellen
Der Tabellenkörper
Verbinden von Zeilen und Spalten
Ausrichtung von Inhalten und Formatierung von Tabellen
Fragen und Antworten
Weitere Absatzelemente
Typische Inline-Elemente
Fußnoten
Referenzen
Texthervorhebungen
Metainformationen
Software-spezifische Elemente
Programmcode
Benutzerschnittstellen
Programmierkonstrukte
Betriebssysteme
Profilieren von DocBook: Teil 1

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

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

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.

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. 

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

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.

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>
(1)

                <title>
(2)

                        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.

book kann part enthalten.

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

Erstellung eines Artikels

article dürfen keine chapter haben

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.

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.