Jedes Stück der Dokumentation in unserem manual Modul ist Teil eines Dokumentensatzes, engl. <set>. Dies ist das allererste Element in der the DocBook-Hierarchie. Ein Dokumentensatz enthält eine Anzahl an Büchern (<book>s), welche wiederum Kapitel (<chapter>s) enthalten, und so weiter.

Ein Vorteil Bücher in einem Dokumentensatzes zu platzieren, ist, dass Sie diese untereinander referenzieren können. Das heißt, Sie könnten beispielsweise Links einfügen, die auf einen Bereich eines anderen Buchs verweisen. Dieser Vorteil wird dadurch relativiert, dass diese Links nicht im PDF funktionieren (im Gegensatz zu HTML). Ein anderer Vorteil ist die automatische Erstellung eines Inhaltsverzeichnisses.

Glücklicherweise bedeutet die Platzierung von Büchern im gleichen Satz nicht, dass diese alle in der gleichen, großen Datei liegen müssen. DocBook erlaubt es Ihnen, ein Hauptdokument, wie im Anschluss gezeigt, anzulegen. (Machen Sie sich keine Gedanken über den Bereich, der mit "<!DOCTYPE" startet – Sie müssen keines dieser fürchterlichen Dinge selbst schreiben. Im schlimmsten Fall müssen Sie diesen Teil nur kopieren und anpassen, wenn Sie einen existierenden Dokumentensatz übersetzen.)

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "docbookx/docbookx.dtd" [
    <!ENTITY preface SYSTEM "firebirddocs/preface.xml">
    <!ENTITY fb-intro SYSTEM "firebirddocs/firebirdintro.xml">
    <!ENTITY ...>
    <!ENTITY ...>
]>

<set id="firebird-books">
  &preface;
  &fb-intro;
  ...
  ...
</set>

Mit dem Einrichten des Hauptdokumentes, wie gerade beschrieben, werden die Bücher in je eigenen Dateien vorgehalten: preface.xml, firebirdintro.xml, etc.. Diese können nun unabhängig voneinander bearbeitet werden. Eine solche Datei - Ihre zum Beispiel - ist allgemein so strukturiert:

<?xml version="1.0" encoding="UTF-8"?>

<book id="fbintro">
  <chapter id="fbintro-preface">
    ...
    ...
  </chapter>
  <chapter id="fbintro-installing-firebird">
    ...
    ...
  </chapter>
  ...
  ...
</book>

Natürlich muss das neue Dokument dem Haupt-Dokumentensatz bekannt gemacht werden, aber das ist etwas worüber wir mit Ihnen sprechen werden, wenn Sie mit dem Schreiben starten. (Wir geben hier keine allgemeine Richtlinie aus, da dies davon abhängt, was Sie schreiben wollen - ein Buch, Artikel, ein oder mehrere Kapitel... - und Ihr Werk soll ja zum Rest passen.)

Jede DocBook-Datei muss mit der folgenden Zeile beginnen:

<?xml version="1.0" encoding="UTF-8"?>

(Hinweis: für einige Sprachen wird UTF-16 eine bessere Wahl sein.)

Wenn Sie Ihre Dokumentation „händisch“ schreiben, z.B. mit einem Texteditor, müssen Sie diese Zeile selbst hinterlegen. Wenn Sie einen speziellen XML-Editor verwenden, wird dies automatisch eingefügt, sobald Sie ein neues Dokument erstellen.

Wenn Sie Ihr DocBook-XML in einem Texteditor wie Notepad, emacs oder ConText bearbeiten, können Sie Zeilenumbrüche, Einrückungen und mehrere Leerzeichen verwenden, wenn Sie möchten. Jedes Auftreten eines Leerraums (engl. whitespace, eine Sequenz von einem oder mehreren Leerzeichen, Tabs, Zeilenvorschüben oder Steuerzeichen) wird in ein einzelnes Leerzeichen in der Ausgabe umgewandelt. So wird aus:

<section><title>Firebird Architectures</title><para>Now let's have a
look at Firebird's different architectures.</para><itemizedlist>
<listitem><para>First, there's the so-called <firstterm>Classic Server
</firstterm>.</para></listitem><listitem><para>Then there is <firstterm>
Superserver</firstterm> architecture.</para></listitem><listitem><para>
And finally, with the release of Firebird 1.5 we also have the 
<firstterm>embedded server</firstterm>.</para></listitem></itemizedlist>
</section>

diese Ausgabe:

<section>
  <title>Firebird Architectures</title>
  <para>Now let's have a look at Firebird's different
    architectures.</para>
  <itemizedlist>
    <listitem>
      <para>First, there's the so-called 
        <firstterm>Classic Server</firstterm>.</para>
    </listitem>
    <listitem>
      <para>Then there is <firstterm>Superserver</firstterm> 
        architecture.</para>
    </listitem>
    <listitem>
      <para>And finally, with the release of Firebird 1.5 we also
        have the <firstterm>embedded server</firstterm>.</para>
    </listitem>
  </itemizedlist>
</section>

Nicht nötig zu sagen, dass die zweite Variante deutlich leichter zu lesen und zu verstehen ist. Wenn Sie also Ihr XML mit der Hand schreiben sollten, formatieren Sie den Text so, dass die Struktur so klar wie möglich ist.

Wenn Sie einen speziellen XML-Editor verwenden, beachten Sie bitte, dass Enter möglicherweise automatisch das aktuelle <para>-Tag schließt und ein neues öffnet. Stellen Sie sicher, dass Sie wissen, wie sich Ihr Editor in diesem Bezug verhält. Prüfen Sie außerdem wie sich der Editor bei zu vielen Leerzeichen verhält. Manche nutzen spezielle Tricks um diese zu behalten.