Firebird Documentation IndexFirebird Docwriting-Anleitung → Bereiten Sie Ihr DocBook-Dokument vor
Firebird Home Firebird Home Zurück: DocBook XML SchreibwerkzeugeFirebird Documentation IndexNach oben: Firebird Docwriting-AnleitungWeiter: Häufig verwendete Elemente

Bereiten Sie Ihr DocBook-Dokument vor

Erstellung des Dokuments
Texte schreiben

Hallo – Sie sind ja noch da! Ich weiss, ich habe viel Zeit darauf verwendet, XML und DocBook zu erklären, aber ich hatte wirklich das Gefühl, dies tun zu müssen, da dies für viele Menschen neue Konzepte sind. Einfach nur ein paar Links in den Raum zu werfen und Sie dann allein zu lassen, würde vermutlich dazu führen, dass uns ein paar brauchbare Schreiber verloren gingen.

Egal, nun sind wir hier: Schlussendlich bereit loszulegen. Schreiben wir unser Dokument. Dieser Abschnitt klärt die Einrichtung Ihres DocBooks; der nächste zeigt wie die korrekten Tags und Attribute an den richtigen Stellen gesetzt werden.

Erstellung des Dokuments

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.

Dateipfade für verschiedene Dokumentensätze

Dateien für das englische Benutzerdokumentations-set liegen im Verzeichnis manual/src/docs/firebirddocs. Nicht-englische Dokumente werden im sprachabhängigen Baum wie z.B. manual/src/docs/firebirddocs-fr, manual/src/docs/firebirddocs-es, etc. abgelegt.

Seit Januar 2006 haben wir die Möglichkeit weitere Basis-Dokumentensätze anzulegen, das erste war rlsnotes, der Satz für Release Notes. Die gleiche Logik finden wir auch hier wieder: Englisches Zeug für die Release Notes liegt unter manual/src/docs/rlsnotes, französisches in manual/src/docs/rlsnotes-fr, und so weiter.

Jeder dieser Verzeichnisbäume – firebirddocs, firebirddocs-es, firebirddocs-nl, rlsnotes, rlsnotes-fr, etc. – beinhaltet ein eigenes <set>, mit einem Hauptdokument und eine beliebige Anzahl Dateien.

Texte schreiben

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.

Zurück: DocBook XML SchreibwerkzeugeFirebird Documentation IndexNach oben: Firebird Docwriting-AnleitungWeiter: Häufig verwendete Elemente
Firebird Documentation IndexFirebird Docwriting-Anleitung → Bereiten Sie Ihr DocBook-Dokument vor