Firebird Documentation IndexFirebird Docwriting-Anleitung → Häufig verwendete Elemente
Firebird Home Firebird Home Zurück: Bereiten Sie Ihr DocBook-Dokument vorFirebird Documentation IndexNach oben: Firebird Docwriting-AnleitungWeiter: Sprache und Stil

Häufig verwendete Elemente

Hierarchische Elemente
Listen
Links
Programm-Listings, Bildschirmausgaben, literales Layout und Beispiele
Tabellen
Bilder
Hinweise
Absatzköpfe
Verschiedene inline-Elemente
Abschluss der Elemente

Dieser Abschnitt behandelt die am häufigsten verwendeten DocBook-Elemente. Er beinhaltet viele Beispiele im DocBook XML-Format. Wenn Sie einen XML-Editor verwenden, wird die Ausgabe vermutlich nichts mit diesen Beispielen zu tun haben. Öffnen Sie Ihre Datei hingegen in einem Texteditor - oder wählen die reine Textansicht in Ihrem XML-Editor - werden Sie den aktuellen XML-Code sehen. Sehen Sie auch die vorhandenen XML-Quellen des manual Modul ein, um herauszufinden wie andere Autoren ihre Dokumente zusammenbauen und Tags zuweisen.

Lesen Sie bitte den Unterabschnitt über hierarchische Elementstrukturen, auch wenn Sie ein professioneller DocBook-Schreiber sind, da es ein paar spezifische Projektvorgaben enthält. Danach können Sie den Rest der DocBook-Unterabschnitte überspringen.

Wenn Sie erstmalig mit DocBook arbeiten, seien Sie nicht von der Länge dieses Abschnitts entmutigt. Mein Rat ist, dass Sie den Abschnitt über hierarchische Elemente gründlich lesen und den Rest überfliegen. Es ist kein Problem, wenn Sie nicht gleich alles verstehen. Das Verständnis kommt bei der Anwendung. Haben Sie diesen Leitfaden nur zur Hand, wenn Sie ihr Dokument schreiben, und schauen Sie immer mal wieder in die Elementabschnitte rein (so wie sie es gerade brauchen).

Hierarchische Elemente

Die allgemeinste Hierarchie, startet mit: <set><book><chapter><section><para>. Ein Buch (book) besteht möglicherweise aus Artikeln (<article>s) anstatt aus Kapiteln (<chapter>s).

Der nächste Unterabschnitt wird einige Aspekte bezüglich der Dokumentstruktur erklären.

Das id-Attribut

Sets, books, chapters, articles und Top-Level-Abschnitte sollten immer ein id-Attribut besitzen. Andere Elemente können ebenfalls eines haben. Die ID erlaubt es uns ein Element von anderen Stellen des Dokuments zu referenzieren, sogar aus anderen Dokumenten innerhalb des Satzes (set). IDs sind nicht sichtbar im gerenderten Dokument (mit Ausnahme des HTML-Quelltextes), aber sie werden verwendet für die Namensvergabe der HTML-Dateien.

Alle id-Attribute müssen eindeutig innerhalb des Buchsatzes (bookset). Beachten Sie, dass die verschiedenen Sprachversionen in je einem eigenen set liegen, wodurch es OK ist, die originalen ids in der Übersetzung zu behalten.

Innerhalb eines Buchs (book) oder Artikels (article), sollten die ids mit den gleichen kleingeschriebenen Wörtern beginnen, z.B. usersguide, gefolgt von einem Trennzeichen, gefolgt von einem oder mehreren kleingeschriebenen Wörtern. Beispiele hierfür sind usersguide-intro und usersguide-download-install. Dies ist keine DocBook-Voraussetzung, sondern unsere eigene Konvention.

Die lang-Attribute in nicht-englischen Dokumentensätzen

Wenn Sie einen neuen Dokumentensatz erstellen, oder einen vorhandenen übersetzen, müssen Sie das Sprachattribut lang im Hauptelement verwenden:

<set id="firebird-books-fr" lang="fr">

Hiermit wird sichergestellt, dass die korrekten Beschriftungen für Hinwise, Warnung, etc. erstellt werden und dass die sprachabhängigen Anführungszeichen verwendet werden. Es ist außerdem eine gute Praxis, diese Attribute für die individuell gestalteten Dokumente zu verwenden, wenn diese jemals außerhalb Ihres Sets erstellt werden.

Für englische Dokumentensätze ist das lang-Attribut optional.

Titles

set, book, chapter, article und section müssen immer ein title-Attribut besitzen – entweder als direktes Kindelement oder innerhalb eines xxxinfo-Elementes (siehe unten). Es ist außerdem möglich diesen in beiden Elementen anzugeben, in diesem Fall jedoch müssen die zwei title identisch sein, unabhängig davon, ob id ein Attribut oder title ein Element ist. Und auch unabhängig davon, ob title in der Ausgabe erscheinen wird.

Wenn title zu lang ist, sollten Sie ein titleabbrev-Element direkt dahinter hinzufügen. Dieses enthält eine gekürzte Fassung des Titels. Der Hauptgrund hierfür ist, dass jede erstellt HTML-Seite eine sogenannte Hierarchieleiste enthält. So eine Art „Sie befinden sich hier-Zeile“ am Beginn und Ende. Diese Hierarchieleiste zeigt Ihnen jede Abstufung vom höchsten Element (dem set) bis runter zu Ihrer aktuellen Seite. Da die Namen auch anklickbar sind, gibt Ihnen die Leiste jederzeit bekannt, wo sich sich gerade innherhalb der Hierarchie befinden. Außerdem ist die Navigation zu höheren Elemente hierdurch kinderleicht. Am besten sieht die Leiste aus, wenn die Namen von der Größe her in eine Zeile passen, gleiches gilt für titleabbrev, welches nur angezeigt wird, wenn es auch vorhanden ist. Ist dies nicht der Fall wird title verwendet. Das gleiche Schema setzt sich für die Lesezeichen (die Navigation im linken Bereich) im PDF-Dokument fort.

Info-Elemente

Wenn Sie ein Buch oder Artikel verfassen, müssen Sie ein bookinfo- oder articleinfo-Element am the Start definieren. Innerhalb dieser können Sie Autoreninformationen und mehr erstellen. Weitere xxxinfo-Elemente existieren, aber Sie werden diese selten benötigen.

<book id='usersguide' lang='en'>
  <bookinfo>
    <title>Firebird Users Guide</title>
    <author>
      <firstname>William</firstname>
      <surname>Shakespeare</surname>
    </author>
    <edition>25 January 2006 – Document version 1.2</edition>
  </bookinfo>
  ...
  ...
</book>

Wenn der Autor einer Firma oder anderen Organisation oder Gruppe angehört, auf die Sie verweisen möchten, nutzen Sie corpauthor anstelle von author:

<corpauthor>IBPhoenix Editors</corpauthor>

Gibt es mehrere Autoren und Sie möchten diese einzeln aufführen, erstellen Sie ein author (oder corpauthor)-Element für jeden von ihnen und fassen Sie diese in einem authorgroup-Element zusammen – alles innerhalb des xxxinfo-Elements.

Abschnittsarten

Abschnittselemente unterscheiden sich etwas vom Rest in zwei Arten:

  • Erstens, das <section>-Element wie zuvor beschrieben. Es kann rekursiv genutzt werden, beispielsweise könnten Sie ein <section> innerhalb eines anderen <section> wiederum innerhalb eines anderen <section>... verschachteln. Dies hat den Vorteil, dass Sie den gesamten Unterbaum hoch und runter wandern können, ohne die Tags zu ändern.

  • Zweitens gibt es den <sect1>, <sect2> ... <sect5>-Bereich. Diese Elemente werden üblicherweise verschachtelt, mit <sect1> am Anfang, <sect2> innerhalb von <sect1> etc. Sie können <sect3> nicht direkt in <sect1> einbinden. Das ist weniger flexibel als <section> und in der Praxis auch nervenaufreibend. Nichtsdestotrotz trifft die gleiche „Rigidität“ auf die Elemente <set>, <book> und <chapter> zu und wir können auch damit leben.

Anmerkung

In früheren Versionen diese Leitfadens, wurde die <sectN>-Methode bevorzugt. Aufgrund von Verbesserungen der Stylesheets ist die jedoch nicht mehr länger der Fall. Nutzen Sie was immer Sie möchten.

Anhänge

Sie können einen oder mehrere appendix-Elemente nach dem letzten Kapitel eines Buches (book) oder nach dem letzten Abschnitt (section) eines Artikels (article) einfügen. Anhänge können alles beinhalten, was auch section beinhalten darf, somit auch weitere Abschnitte.

Beispielstruktur

Das folgende Beispiel soll Ihnen einen Anhaltspunkt geben, wie Ihr Dokument aufgebaut sein sollte:

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

<book id="usersguide">

  <bookinfo>
    <title>Firebird Users Guide</title>
    <author>
      <firstname>William</firstname>
      <surname>Shakespeare</surname>
    </author>
    <edition>25 January 2006 – Document version 1.2</edition>
  </bookinfo>

  <chapter id="usersguide-intro">
    <title>Introduction</title>
    <para>Hello! This is the introductory text to the Firebird
      Users Guide.</para>
  </chapter>

  <chapter id="usersguide-download-install">
    <title>Downloading and installing Firebird</title>
    <para>In this chapter we'll demonstrate how to download and
      install Firebird.</para>
    <section id="usersguide-download">
      <title>Downloading Firebird</title>
      <para>To download Firebird from the Internet, first go to the
        following URL: etc. etc. etc.</para>
      ...more paragraphs, possibly subsections...
    </section>
    <section id="usersguide-install">
      <title>Installing Firebird</title>
      <para>Installing Firebird on your system goes like this:
        etc. etc.</para>
      ...more paragraphs, possibly subsections...
    </section>
  </chapter>

  ...more chapters...

  <appendix id="usersguide-dochist">
    <title>Document history</title>
    ...to be discussed later!

  <appendix id="usersguide-license">
    <title>License notice</title>
    ...to be discussed later!
</book>

Zu beachtende Punkte

  • Beachten Sie zunächst wieder, dass Attribute in Anführungszeichen stehen. (Wenn Sie diese mit einem Attributeditor einsetzen, werden diese vom Programm selbst gesetzt.)

  • Wie Sie im Beispiel sehen, können chapters und sections direkt mit einem oder mehreren para-Elementen starten. Sobald Sie aber Abschnitte (section) in einem Kapitel einbinden, oder Unterabschnitte in einem Abschnitt, können Sie keine weiteren para-Elemente danach verwenden - nur noch innerhalb dieser. Gute DocBook-XML-Editoren werden Sie dies auch nicht tun lassen. Wenn Sie Ihr DocBook-XML jedoch händisch erstellen, sollten Sie hierauf achten.

  • Wenn Sie einen XML-Editor einsetzen, werden Sie vermutlich selten para-Elemente selbst erstellen. Füge ich beispielsweise ein chapter oder ein section im XMLMind XML Editor ein, wird automatisch ein – zunächst leerer – para erstellt. Und wenn ich dann Text im Absatz eingebe und ENTER drücke, wird dieser Absatz automatisch mit einem </para> geschloseen und der nächste wird erstellt.

Überspringen Sie den Rest des Elemente-Unterabschnitts , sollten Sie schon alles über DocBook-Elemente wissen.

Listen

DocBook bietet verschiedene Listenelemente. Dies sind die gebräuchlichsten:

itemizedlist

Ein itemizedlist wird verwendet, um eine ungeordnete Aufzählungen zu erstellen:

<itemizedlist spacing="compact">
  <listitem><para>Oranges are juicy</para></listitem>
  <listitem><para>Apples are supposed to be healthy</para></listitem>
  <listitem><para>Most people find lemons way too sour</para>
    </listitem>
</itemizedlist>

Listeneinträgen werden allgemein mit Punkten vorangestellt angezeigt:

  • Oranges are juicy

  • Apples are supposed to be healthy

  • Most people find lemons way too sour

Wenn Sie das spacing-Attribut weglassen, wird der Standard normal genutzt, was bedeutet, das vertikale Leerräume (typischerweise eine Zeilenhöhe) zwischen den Listeneinträgen eingefügt wird.

orderedlist

Ein orderedlist erzeugt eine geordnete Aufzählung, auch Nummerierung genannt:

<orderedlist spacing="compact" numeration="loweralpha">
  <listitem><para>Sumerians 3300 BC – 1900 BC</para></listitem>
  <listitem><para>Assyrian Empire 1350 BC – 612 BC</para></listitem>
  <listitem><para>Persian Empire 6th century BC – 330 BC</para>
  </listitem>
</orderedlist>

Standardmäßig werden Zahlen (1, 2, 3, ...) verwendet, die vor den Listeneinträgen erscheinen, aber diese können Sie mit dem Attribut numeration ersetzen lassen. Ausgabe:

  1. Sumerians 3300 BC – 1900 BC

  2. Assyrian Empire 1350 BC – 612 BC

  3. Persian Empire 6th century BC – 330 BC

procedure

Ein procedure wird häufig wie ein orderedlist dargestellt, ist semantisch aber etwas anderes: ein procedure beschreibt eine bestimmte Schrittfolge:

<procedure>
  <step><para>Pick the lock</para></step>
  <step><para>Rob the house</para></step>
  <step><para>Get arrested</para></step>
</orderedlist>

So sieht die Ausgabe aus:

  1. Pick the lock

  2. Rob the house

  3. Get arrested

Innerhalb eines step, können Sie einen Unterschritt substeps erstellen, welcher wiederum weitere step-Elemente enthalten kann.

variablelist

Ein variablelist besteht aus Einträgen der Art varlistentry, welche jeweils ein term beinhalten, gefolgt von einem listitem:

<variablelist>
  <varlistentry>
    <term>Tag</term>
    <listitem>
      <para>A piece of text enclosed in angle brackets</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Element</term>
    <listitem>
      <para>A start tag, a matching end tag, and everything in 
        between</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Content of an element</term>
    <listitem>
      <para>Everything between the matching tags</para>
    </listitem>
  </varlistentry>
</variablelist>

Die Liste, die Sie gerade lesen, besteht aus verschiedenen Listentypen und ist selbst ein variablelist mit den Elementnamen (itemizedlist, orderedlist, etc.) als Einträge. Der nächste Abschnitt – Links – besteht ebenfalls aus einem Einleitungssatz gefolgt von einem variablelist.

Links

Sie können Hyperlinks zu Zielen innerhalb Ihres Dokuments, zu einem anderen Dokument in ihrem Dokumentensatz (set) oder im Internet.

link

link ist das allgemeine Element, das auf einem anderen Ort im Dokument oder Dokumentensatz (set) verweist. Das Attribut linkend muss immer vorhanden sein; sein Wert sollte die id des zu verlinkenden Elements ( link target) sein.

Click <link linkend="docwritehowto-introduction">here</link> to jump
to the introduction.

Im gerenderten Dokument, ist „here“ ein hot text, das heißt: ein anklickbarer Link, der zur Einleitung verweist:

Click here to jump to the introduction.

Achtung

Obwohl Sie link nutzen können, um auf ein beliebiges Element im gesamten Dokumentensatz (set) zu verlinken, sollten Sie dies jedoch nur für tun, wenn das Ziel auch im gleichen PDF exisitert. Die HTML-Version ist voll verlinkbar, die Ausgabe des PDF-Rendering hingegen, funktioniert nicht Dokumentübergreifen. Unsere PDFs enthalten typischerweise ein Buch (book) oder Artikel (article); wenn sich das Ziel außerhalb des aktuellen Dokuments befindet, nutzen Sie stattdessen ulink (siehe unten).

ulink

Verwenden Sie ulink um eine Internetresource zu verlinken. Das Attribut url ist selbsterklärend:

Click <ulink url="http://docbook.org/tdg/en/">this link</ulink> to
read The Definitive Guide on DocBook.

Die Wörter „dieser Link“ werden als Hyperlink zu http://docbook.org/tdg/en/ dargestellt, in etwa:

Click this link to read The Definitive Guide on DocBook.

email

Sie können einen E-Mail-Link mit ulink erstellen, es ist jedoch leichter das Element email zu benutzen. Dieses wird die E-Mail-Adresse als klickbaren Link in der Ausgabe anzeigen. Dieser XML-Code:

Send mail to 
<email>firebird-docs-request@lists.sourceforge.net</email> to 
subscribe.

wird in der Ausgabe zu:

Send mail to to subscribe.

Wenn Sie möchten, dass sich der hot text von der E-Mail-Adresse selbst unterscheidet, verwenden Sie ulink mit einer mailto:-URL.

Warnung

Wenn Sie Links zu E-Mail-Adressen einbinden, entweder mittels email oder ulink – oder wenn Sie dies nur andenken, und Ihr Dokument im Internet veröffentlicht wird, werden diese Adressen schnell von Spamern genutzt. Dies wird den Anteil von Spam für diese Adressen deutlich erhöhen. Stellen Sie also vorher sicher, dass der Eigentümer der Adresse sich auch einverstanden mit der Veröffentlichung zeigt!

anchor

Ein anchor (Ankerelement) ist ein leeres Element, dass eine genaue Position im Dokument auszeichnet. Es zeigt sich im lesbaren Text, aber es kann für ein Linkziel verwendet werden. Das ist nützlich, wenn Sie eine Stelle inmitten eines langen Absatzes verlinken wollen:

<para id="lost-at-sea">
  Blah blah blah...
  and some more...
  and then some...
  Now here's an interesting place in the paragraph I want to be able
  to link to:
  <anchor id="captain-haddock"/>There it is!
  Paragraph drones on...
  and on...
  and on...
</para>

Sobald der Anker platziert ist, können Sie hierhin verlinken:

<link linkend="captain-haddock">Go to the interesting spot</link> in
that long, long paragraph.

Wenn Ihr Link auf ein kurzes Element oder den Anfang eines Elements zeigt, ist es einfacher, dem Zielelement ein id-Attribut zu geben und dies als Verlinkung zu verwenden.

Programm-Listings, Bildschirmausgaben, literales Layout und Beispiele

programlisting (Programm-Listings)

Wenn Sie Code-Fragmente in Ihrem Dokument unterbringen wollen, packen Sie diese in ein programlisting-Element. Alles, was Sie innerhalb eines Programm-Listings schreiben, wird wörtlich, inklusive Zeilenumbrüche, Leerzeichen, etc., in die Ausgabe übernommen. Des weiteren wird eine Schriftart mit fester Zeichenbreite verwendet. Der Begriff „Programm-Listing“ ist im weiteren Sinne zu verstehen: Sie sollten das Element auch für SQL- und DocBook XML-Anweisungen und -Beispiele nutzen. Dieser Leitfaden - und insbesondere der Abschnitt über Elemente, welchen Sie gerade lesen - ist zugemüllt mit programlistings, also wissen Sie bereits wie diese aussehen:

Programlistings are rendered like this.

Wichtig

In Programm-Listings sollten Sie die Zeilenweite auf 70 Zeichen beschränken. Andernfalls wird der Text in PDFs rechts über den Rand laufen. Das gleiche gilt für andere Elemente wie screen, literallayout, etc.

screen (Bildschirmausgaben)

Verwenden Sie ein Element screen, um zu zeigen, was ein Anwender sieht oder sehen sollte, wenn sich im Textmodus oder Terminalmodus befindet. Hier wird das Layout ebenfalls durch eine Festbreitenschrift dargestellt, aber die Semantic ist eine andere. In der Ausgabe unterscheided sie sich nicht vom Programm-Listing. Hier ein kurzes Beispiel, was passiert, wenn Sie versuchen ein nichtexistierendes Ziel im manual-Baum zu erstellen:

<screen>
D:\Firebird\manual_incl_howto\src\build>build ugh
java version "1.4.2_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06)
Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode)

Buildfile: build.xml

BUILD FAILED
Target `ugh' does not exist in this project.
</screen>

Und so sieht die Ausgabe aus:

D:\Firebird\manual_incl_howto\src\build>build ugh
java version "1.4.2_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06)
Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode)

Buildfile: build.xml

BUILD FAILED
Target `ugh' does not exist in this project.
literallayout (wörtliches Layout)

literallayout, wie screen und programlisting hält Ihr Layout intakt und ändert die Schriftart normalerweise nicht - es sei denn Sie setzen das Attribut class auf monospaced. Es ist ein allgemeineres Element, als die zwei vorhergehenden. Seinem Inhalt wird keine Bedeutung zugemessen: Sie können irgendeine Art Text hier platzieren, wenn Sie das Layout erhalten wollen.

Beispiel (Quelltext):

<literallayout>
The Sick Rose

Oh Rose, thou art sick!
The invisible worm
That flies in the night,
In the howling storm,

Has found out thy bed
Of crimson joy,
And his dark secret love
Doth thy life destroy.

  — William Blake
</literallayout>

Beispiel Ausgabe:

The Sick Rose

Oh Rose, thou art sick!
The invisible worm
That flies in the night,
In the howling storm,

Has found out thy bed
Of crimson joy,
And his dark secret love
Doth thy life destroy.

  — William Blake

example (Beispiel)

Ein example stellt ein formales Beispiel samt Titel dar. Es wird normalerweise mit einem id-Attribut verwendet, womit es an anderen Dokumentstellen referenziert werden kann. Ein Beispielverzeichnis wird automatisch erstellt, wenn das Dokument gerendert wird. Sie werden häufig programlistings ein einem example finden, aber es kann auch screens, paras, lists, etc. enthalten.

Hier ist ein Beispiel für die Verwendung von example:

<example id="docwritehowto-sql-example">
  <title>Ein SQL-Beispiel</title>
  <para>Mit diesem Befehl können Sie alle Datensätze der Tabelle COUNTRY auflisten:</para>
  <programlisting>SELECT * FROM COUNTRY;</programlisting>
</example>

In der Ausgabe sieht dies so aus:

Beispiel 1. Ein SQL-Beispiel

Mit diesem Befehl können Sie alle Datensätze der Tabelle COUNTRY auflisten:

SELECT * FROM COUNTRY;


Wenn Sie ein Beispiel ohne zwingenden Titel erstellen möchten, verwenden Sie informalexample. Informelle Beispiele sind nicht Bestandteil des Beispielverzeichnisses.

Tabellen

Wenn Sie schonmal eine Tabelle in HTML erstellt haben, werden Sie auch keine großen Schwierigkeiten bei der Erstellung von Tabellen mittels DocBook haben. Es gibt ein paar Unterschiede, und DocBook-Tabellen sind weit mächtiger.

Ein Element table besteht aus einem title und einer oder mehreren tgroups – übrlicherweise eine. Das tgroup-Element besitzt ein notwendiges Attribut: cols. Hierfür sind die Anzahl der Spalten innerhalb des tgroup anzugeben. Innerhalb eines tgroup können Sie die Elemente thead, tfoot und tbody platzieren. Jedes dieser Elemente hat ein oder mehrere Zeilen (engl. rows), welche wiederum so viele Zellen (engl. entrys) beinhalten, wie Sie zuvor im Attribut cols angegeben haben. (Sie können Zellen verbinden, aber das wird hier nicht behandelt.)

Soviel zu Basisstruktur. Jetzt werden wir Ihnen ein Beispiel zeigen; Erst als DocBook XML-Quelltext, und dann die resultierende Tabelle in der gerenderten Ausgabe. Machen Sie sich keine Gedanken über die <colspec>s; Dies sind keine Pflicht-Unterlemente. Sie sind nur zum Feintuning da.

<table id="docwritehowto–table–dboftheyear">
  <title>LinuxQuestions.org poll: Database of the year 2003</title>

  <tgroup cols="3">
    <colspec align="left" colname="col–dbname" colwidth="2*"/>
    <colspec align="right" colname="col–votes" colwidth="1*"/>
    <colspec align="right" colname="col–perc" colwidth="1*"/>

    <thead>
      <row>
        <entry align="center">Database</entry>
        <entry align="center">Votes</entry>
        <entry align="center">Percentage</entry>
      </row>
    </thead>

    <tfoot>
      <row>
        <entry>Total</entry>
        <entry>1111</entry>
        <entry>99.99</entry>
      </row>
    </tfoot>

    <tbody>
      <row>
        <entry>MySQL</entry>
        <entry>405</entry>
        <entry>36.45</entry>
      </row>
      <row>
        <entry>Firebird</entry>
        <entry>403</entry>
        <entry>36.27</entry>
      </row>

      ... 5 more rows not shown here ....

    </tbody>
  </tgroup>
</table>

Und hier ist die resultierende Tabelle:

Tabelle 2. LinuxQuestions.org poll: Database of the year 2003

Database Votes Percentage
Total 1111 99.99
MySQL 405 36.45
Firebird 403 36.27
Postgres 269 24.21
Oracle 25 2.25
Berkeley DB 4 0.36
Sybase 3 0.27
DB2 2 0.18


Nebenbei ist dies ein reeller Auszug von LinuxQuestions.org. Wie Sie sehen können, fehlen lediglich drei Leute, die zum Sieg für Firebird hätten stimmen müssen. Wenn Sie diese drei Personen kennen, kontaktieren Sie bitte unseren Chef-Inquisitor. Er würde gern ein kleines, ähm... Gespräch mit ihnen führen :–)

Tabellen werden automatisch inidziert. Ein informaltable hat die gleiche Struktur wie ein table, benötigt aber keinen Titel und wird nicht im Tabellenverzeichnis geführt. Wenn Sie Tabellen verschachteln wollen, nutzen Sie entweder table/informaltable innerhalb eines entry oder ein entrytbl anstelle eines entry.

Tabellen haben deutlich mehr Eigenschaften als hier gezeigt, aber dies sei nun an Ihnen herauszufinden.

HTML-Tabellen

DocBook in den Versionenen 4.3 und höher erlaubt es Ihnen, Tabellen im HTML-Stil zu erstellen. Somit ist die Verwendung von trs anstelle von rows und td/th anstelle von entry erlaubt. Warum sollten Sie das tun? Es gibt zwei Situationen, in denen die Verwendung der HTML-Tabellen vorteilhaft ist:

  • Sie haben bereits eine vorhandene HTML-Tabelle und möchten nicht die Zeit investieren, diese zu konvertieren;

  • Sie möchten verschiedene Hintergrundfarben in der Tabelle verwenden. Dies kann zwar auch in der DocBook-Tabelle getan werden, aber nur mit Verarbeitungsanweisungen, also den processing instructions – eine für jedes Ziel jedes Elementes, das eine eigene Farbe erhalten soll. In einer HTML-Tabelle können Sie das Attribut bgcolor des Kindelements verwenden.

Eine HTML-Tabelle darf keine tgroups enthalten; verwenden Sie trs entweder direkt in der Tabelle oder im Tabellenkopf thead / Tabellenkörper tfoot / Tabellenfuß tbody. Diese sind direkte Kindelemente der Tabelle selbst. Außerdem hat die HTML-Tabelle das Element caption anstelle von title. (Ein informaltable-Element hat weder caption noch title.)

Hier ist der Quelltext einer HTML-Tabelle:

<table bgcolor="blue" border="1">
  <caption align="bottom">An HTML-style table</caption>

  <tr bgcolor="#FFE080">
    <th>First column</th>
    <th bgcolor="#FFFF00">Second column</th>
  </tr>
  <tr align="center">
    <td bgcolor="orange" colspan="2">Table cell spanning two
      columns</td>
  </tr>
  <tr>
    <td bgcolor="#00FFC0">Yes, here I am</td>
    <td align="right" bgcolor="#E0E0E0" rowspan="2" valign="bottom">And
      there I go!</td>
  </tr>
  <tr>
    <td bgcolor="#FFA0FF">Another row...</td>
  </tr>
</table>

Und hier ist das Ergebnis:

Tabelle 3. An HTML-style table
First column Second column
Table cell spanning two columns
Yes, here I am And there I go!
Another row...

Nicht alle HTML-Tabellenelemente und -attribute werden von den Stylesheets unterstützt. So werden beispielsweise Eigenschaften, die in col und colgroup definiert wurden, nicht berücksichtigt. Definieren Sie diese stattdessen in td-/th-Elementen - oder erweitern Sie die Stylesheets!

Anmerkung

In XMLMind können Sie eine HTML-Tabelle über das Menü in der Werkzeugleiste erstellen. Über den Bearbeiten-Bereich können Sie lediglich DocBook-Tabellen erstellen.

PDF-Ausgabe großer Tabellen

DocBook tables gehören zu den sogenannten formalen Elementen (engl. formal elements). Formale Elemente werden automatisch in Verzeichnisse aufgenommen (Tabellenverzeichnis, Abbildungsverzeichnis, etc.); wenn ein formales Element kein Attribut id besitzt, weist ihm das Stylesheet eines zu. Die Vorlage, die die XSL-FO-Ausgabe generiert (den Zwischenschritt hin zum PDF), weist jedem formalen Objekt auch das Attribut keep-together.within-page="always" zu, was verhindert, dass Seitenumbrüche innerhalb eines Objekts stattfinden. Dies ist normalerweise gewünscht, aber was passiert, wenn das Objekt nicht auf eine Seite passt? Bis vor kurzem nutzten wir Apache FOP 0.20.5 um die XSL-FO-Ausgabe zu erstellen. Dieser Prozessor ignorierte das keep-together-Attribut, wenn das Objekt zu groß war. Aber die derzeitige Version (0.93 oder höher) "drückt" diese Eigenschaft immer durch. Das Ergebnis ist, dass das Obejekt in diesem Falle abgeschnitten (oder in irgendeiner anderen Art passend gemacht) wird, damit es auf die Seite passt. Dies ist ein Feature, kein Bug. Somit gibt es auch keinen Grund sich hierüber zu beschweren.

Es gibt zwei Workarounds, sollte eine Tabelle zu groß für eine Seite sein:

  1. Wenn die Tabelle keinen Titel benötigt und es Ihnen nichts ausmacht, dass diese nicht im Tabellenverzeichnis aufgelistet wird, verwenden Sie stattdessen informaltable.

  2. Fügen Sie eine Verarbeitungsanweisung (processing instruction) am Anfang der Tabell ein:

    <table frame="all" id="ufb-about-tbl-features">
      <?dbfo keep-together='auto'?>
      <title>Summary of features</title>

    In XMLMind wird dies folgendermaßen umgesetzt:

    1. Setzen Sie den Cursor in das Titelelement.

    2. Wählen Sie Edit -> Processing Instruction -> Insert Processing Instruction Before aus dem Menü. Eine grüne Zeile erscheint oberhalb des Titels.

    3. Geben Sie keep-together='auto' in diese Zeile ein.

    4. Lassen Sie den Cursor auf der grünen Zeile, wählen Sie dann Edit -> Processing Instruction -> Change Processing Instruction Target aus dem Menü. Nun erscheint eine Dialog-Box.

    5. Ändern Sie target in dbfo und klicken Sie auf OK.

    Natürlich können Sie das Gleiche für kleinere Tabellen tun, wenn Sie dort Zeilenumbrüche bevorzugen. Die gegenteilige Anweisung <?dbfo keep-together='always'> wird Seitenumbrüche in informaltables verhindern. Stellen Sie sicher, dass die Elemente auf eine Seite passen, bevor Sie dies verwenden!

Bilder

Um Bilder einzubinden, verwenden Sie mediaobject welches ein imageobject beinhaltet, das wiederum ein imagedata beinhaltet:

<mediaobject>
  <imageobject>
    <imagedata align="center" fileref="images/services.png"
      format="PNG"/>
  </imageobject>
</mediaobject>

Vielleicht wundern Sie sich, dass 3 verschachtelte Elemente benötigt werden, um ein simples Bild einzubinden. Hierfür gibt es einen guten Grund, den werde ich Ihnen aber nicht erzählen ;-) - der ist für uns nicht von Belang. Wir müssen nur wissen, dass es so gemacht wird.

Ungeachtet des Bildverzeichnisses, welches relativ zur DocBook-Quelle steht, sollte fileref immer in der Form images/filename.ext angegeben werden. Die geschieht, weil die HTML- und die FO-Ausgabe die Bilddateien aus ihren Quellverzeichnissen zu einem Unterverzeichnis namens images im Ausgabepfad kopieren werden. (Die FO-Ausgabe ist eine Zwischenform. Sobald dies zum PDF gewandelt wurde, ist das Bild in der Datei selbst enthalten.)

Wenn die Dateireferenz nicht „korrekt“ aus Sicht der Dateiquellen ist, werden Sie das Bild in XMLMind auch nicht sehen. Sollte Sie das stören, erstellen Sie einen Symlink auf den Bildordner (Linux) oder kopieren Sie diesen in das gleiche Verzeichnis wie die Quelldatei (Windows). Eine Verknüpfung scheint unter Windows nicht zu funktionieren. Nutzen Sie die Kopien nur in Ihrer lokalen Kopie - erstellen Sie keinen Commit mit doppelten Bilddaten ins CVS!

Ein mediaobject wird als separater Block formatiert. Wenn Sie das Bild mit Text eibinden wollen, nutzen Sie stattdessen inlinemediaobject; die verschachtelten Element bleiben wie sie sind.

Hinweis für Übersetzer

Übersetzer: Alle Bilder, die Sie nicht für Ihre Sprache überarbeiten oder ersetzen, sollten nicht in Ihren sprachabhängigen Dokumentensatz (set) übernommen werden. Seit Januar 2006 sehen die build tools erst in Ihrem Sprachverzeichnis (z.B. manual/src/docs/firebirddocs-fr/images), und danach in manual/src/docs/firebirddocs/images. Somit wird kein CVS-Speicher verschwendet, wenn Sie die Originalbilder verwenden.

Das gleiche Verhalten ergibt sich für die anderen Sätze: Wenn ein Bild von, sagen wir mal spanischen Release Notes, referenziert wird, und dieses nicht in rlsnotes-es/images vorliegt, wird dieses aus rlsnotes/images verwendet. Es funktioniert nicht sprach-übergreifend.

Hinweise

DocBook besitzt mehrere Tags, um einen Textblock als Hinweis, Warnung, Tipp, etc. zu markieren. In der Ausgabe werden solche Blöcke eingerückt und mit einem Symbol oder Wort zur Kennzeichnung ihres Zwecks markiert. Die verwendbaren Tags in alphabetischer Reihenfolge:

<caution>, <important>, <note>, <tip>, und <warning>

Ich werde Ihnen einen Tipp (<tip>) als Beispiel zeigen; Die anderen werden genauso verwendet:

<tip>
  <para>If you insert a caution, important, note, tip, or warning
    element in your text, don't start it with the word caution, 
    important, note, tip, or warning, because these words are usually 
    automatically generated by the rendering engine.</para>
</tip>

Und dies ist die Ausgabe:

Tipp

If you insert a <caution>, <important>, <note>, <tip>, or <warning> element in your text, don't start it with the word caution, important, note, tip, or warning, because these words are usually automatically generated by the rendering engine.

Sie haben vielliecht bemerkt, dass die Wörter caution, important etc. sich vom Aussehen des restlichen Tipp-Textes unterscheiden. Wie kommt das? Um Ihnen die Wahrheit zu sagen, habe ich diese mit speziellen Tags umschlossen (erst mit <sgmltag>s, zweitens mit <literal>s) damit sie nun so aussehen wie sie hier erscheinen. Aber das ließ den XML-Quelltext sehr unsauber aussehen. Deshalb entschied ich mich diese Tags aus den Beispielquellen zu entfernen.

Optional können Sie den Hinweisen ein Element title mitgeben. Wenn Sie dies nicht tun, wird ein Standardkopf (in Dokumentsprache) für die Ausgabe erstellt.

Möchten Sie einen Textblock erstellen ohne diesen als Tipp oder anderes zu kennzeichnen, nutzen Sie <blockquote>.

Absatzköpfe

Wenn Sie einen Absatzkopf oder Titel ohne Unterabschnitt erstellen möchten, gibt es ein paar Möglichkeiten.

bridgehead

Ein bridgehead ist ein flussfreier Titel zwischen Absätzen, der keinem Anfang eines Kapitels oder Abschnitts zugeordnet ist. Das Attribut renderas gibt an, wie es gerendert wird.

<para>You may remember that Mr. Hardy started with this firm as
  elevator boy and with grim determination worked his way up to
  the top. And after the wedding today he becomes General Manager
  of this vast organisation.</para>

<bridgehead renderas="sect5">Mr. Laurel's comments</bridgehead>

<para>We also spoke to his lifetime friend and companion Mr. Laurel.
  Mr. Laurel says that after viewing the situation from all sides,
  he is thoroughly reconciled to the fact that the moving picture
  industry is still in its infancy. Mr. Laurel also states that
  technology, whilst it may appear to be the center of all—</para>

Der oben angegebene Quelltext erscheint so in der Ausgabe:

You may remember that Mr. Hardy started with this firm as elevator boy and with grim determination worked his way up to the top. And after the wedding today he becomes General Manager of this vast organisation.

Mr. Laurel's comments

We also spoke to his lifetime friend and companion Mr. Laurel. Mr. Laurel says that after viewing the situation from all sides, he is thoroughly reconciled to the fact that the moving picture industry is still in its infancy. Mr. Laurel also states that technology, whilst it may appear to be the center of all—

Sie können frei wählen, welchen Level Sie für renderas nutzen wollen, aber logischerweise wird dies meist die derzeitige Ebene plus (mindestens) eins sein.

formalpara

Ein formalpara ist ein Absatz mit Titel. Unsere Stylesheets rendern den Titel als mitlaufenden Kopf.

<formalpara>
  <title>Motherly love:</title>
  <para>This is the love your mother has for you, not to be
    confused with brotherly or otherly love.</para>
</formalpara>

In der Ausgabe erscheint damit:

Motherly love: This is the love your mother has for you, not to be confused with brotherly or otherly love.

Eine Abgrenzung wird zum Titel hinzugefügt, sofern es nicht bereits auf ein Satzzeichen (Doppelpunkt) endet.

Verschiedene inline-Elemente

Zum Abschluss dieses Abschnitts zu DocBook-Elementen, werde ich noch eine Kurzbeschreibung zu einigen Inline-Elementen (inline elements) geben. Sie heißen „inline“, da sie den Fluss des Textes nicht beeinflussen. Wenn ich zum Beispiel das Element emphasis benutze:

Don't <emphasis>ever</emphasis> call me fat again!

ist das Ergebnis:

Don't ever call me fat again!

Das Wort „ever“ wird betont, aber es behält seinen Platz im Satz. Wir haben bereits einige Inline-Elemente kennengelernt: die verschiedenen Linkarten. Andere Elemente - wie table, warning, blockquote und programlisting – werden immer als Block dargestellt, abgesetzt vom umlaufenden Text (selbst wenn Sie diese als „inline“ in Ihrem XML-Quelltext setzen). Nicht überraschend ist somit, dass diese Block-Elemente (block elements) genannt werden. Block-Elemente beinhalten häufig Inline-Elemente; andersherum ist es nicht möglich.

OK, starten wir mit diesen Inline-Elementen. Ich werde Beispiele - jeweils mit XML-Quelltext und als gerenderte Ausgabe - für die meisten zeigen:

filenamecommandapplicationenvar

Verwenden Sie das Tag filename um einen Dateinamen im weitesten Sinne zu markieren. Optionale Attribute können außerdem anzeigen, ob es sich hierbei um eine Headerdatei, ein Verzeichnis, etc. handelt.

Place your doc in the <filename
class="directory">src/docs/firebirddocs</filename> subdirectory.

Die Ausgabe:

Place your doc in the src/docs/firebirddocs subdirectory.

command und application kennzeichnen beide ausführbare Programme. command wird üblicherweise für kleinere Programme und interne Befehle verwendet; sein Inhalt sollte der exakt einzugebende Befehl sein; application wird grundsätzlich für größere Programme verwendet. Der Name der ausführbaren Datei wird nicht benötigt. Beide können auf das gleiche Programm verweisen:

Type <command>netscape&amp;</command> in a terminal window to start 
<application>Netscape Navigator</application>.

Dies ist die Ausgabe:

Type netscape& in a terminal window to start Netscape Navigator.

envar kennzeichnet eine Umgebungsvariable.

subscriptsuperscript

Die zwei Elemente im Einsatz:

After inventing the formula e = mc<superscript>2</superscript>, I 
really felt like a glass of liquid H<subscript>2</subscript>O !

Ausgabe: After inventing the formula e = mc2, I really felt like a glass of liquid H2O !

varnameconstantdatabase

Die Verwendung von varname und constant sollte offensichtlich sein. Das Tag <database> kann für Datenbankobjekte verwendet werden, muss aber nicht:

The <database class="table">COUNTRY</database> table has two fields:
<database class="field">COUNTRY</database> and
<database class="field">CURRENCY</database>.

Ausgabe: The COUNTRY table has two fields: COUNTRY and CURRENCY.

functionparameterreturnvalue

Diese drei sprechen für sich selbst, glaube ich.

The <function>log</function> function takes parameters
<parameter>a</parameter> and <parameter>b</parameter>.

Ausgabe: The log function takes parameters a und b.

promptuserinputcomputeroutput

prompt wird für eine Zeichenkette verwendet, die anzeigt, dass der Benutzer eine Eingabe tätigen soll; userinput verweist auf den eingegebenen Text (nicht zwangsweise in der Befehlszeile!); computeroutput ist der Text, der vom Computer ausgegeben wurde:

Type <userinput>guest</userinput> at the <prompt>login:</prompt>
prompt and the server will greet you with a <computeroutput>Welcome,
guest user</computeroutput>.

Ausgabe: Type guest at the login: prompt and the server will greet you with a Welcome, guest user.

keycap

Der Text einer Taste, oder allgemeiner:

Hit the <keycap>Del</keycap> key to erase the message, or
<keycap>SPACE</keycap> to move on.

Ausgabe: Hit the Del key to erase the message, or SPACE to move on.

sgmltag

Dieses Element wird innerhalb dieses Leitfadens ausführlich genutzt: Es markiert marks SGML und XML-Tags, Elemente, Attribute, Einträge, etc.:

If it concerns a directory, set the 
<sgmltag class="attribute">class</sgmltag> attribute of the 
<sgmltag class="element">filename</sgmltag> element to
<sgmltag class="attvalue">directory</sgmltag>.

Ausgabe: If it concerns a directory, set the class attribute of the filename element to directory.

Andere mögliche Werte für sgmltag.class sind: starttag, endtag, emptytag, und genentity (für einen Eintrag).

emphasiscitetitlefirstterm

Verwenden Sie emphasis um Wörter zu betonen, citetitle für Buchtitel, etc., und firstterm wenn Sie Ihren Lesern ein neues Wort oder Konzept vorstellen:

We use <firstterm>DocBook XML</firstterm> for our Firebird 
documentation. A short introduction follows;
<emphasis>please</emphasis> read it carefully! If you want to know
more about the subject, buy <citetitle>DocBook – The Definitive 
Guide</citetitle>.

Ausgabe: We use DocBook XML for our Firebird documentation. A short introduction follows; please read it carefully! If you want to know more about the subject, buy DocBook – The Definitive Guide.

quoteliteral

Verwenden Sie quote für einen Inline-Bereich, der in Anführungszeichen steht (im Gegensatz zu blockquote). Anführungszeichen werden automatisch eingefügt. Die Nutzung von quote anstelle der Eingabe von Anführungszeichen durch Sie selbst (was natürlich auch möglich ist), hat den Vorteil, dass wir die Art der Anführungszeichen jederzeit durch unsere Stylesheets anpassen können, wenn wir wollen. Außerdem unterscheiden sich die Anführungszeichen von Sprache zu Sprache:

<para>An <quote lang="en">English quote</quote>
  and a <quote lang="fr">French quote</quote>.</para>

Ausgabe: An “English quote” and a « French quote ».

Bitte beachten Sie, dass Sie das Attribut lang nicht zusammen mit quotes innerhalb Ihres eigenen Dokuments verwenden. Ihr Wurzelelements lang-Attribut wird sicherstellen, dass das korrekte Anführungszeichen verwendet wird. Wenn jemand Ihr Dokument übersetzt - und das Wurzel-lang-Attribut ändert – wird es mit den Anführungszeichen der Zielsprache gerendert. Natürlich hatte ich dieses Attribut hier zu verwenden, um die Unterschiede zu zeigen.

Ein literal ist ein Wort oder Textfragment, dass literal (buchstäblich) wiedergegeben wird. Es ist ein allgemeines Element, häufig verwendet, um Wörter typografisch auszuweisen:

At all costs avoid using the word <literal>humongous</literal> in
your documentation.

Ausgabe: At all costs avoid using the word humongous in your documentation.

Sollten Sie diese Elemente wann immer möglich verwenden? Nunja, wenn Sie es tun, werden Sie Ihr Dokument sicherlich reichhaltiger machen; Sie machen es z.B. leichter, nach Dateinamen zu scannen oder ein Verzeichnis aller genutzten Anwendungen zu erstellen. Auf der anderen Seite gibt es so viele dieser semantischen Elemente (tatsächlich haben wir nur einige hier besprochen), dass Sie die Segel streichen werden, wenn Sie alle anwenden wollten. Das ist nicht unser Anliegen: Wenn Sie sich wirklich verrückt machen wollen, tun Sie dies bitte nachdem Sie Ihr Dokument comitted haben :-)

Somit gilt als allgemeiner Rat: gehen Sie behutsam mit diesen Elementen um; verwenden Sie sie dort, wo es nach Ihrem ermessen Sinn macht, aber übertreiben Sie es nicht.

Abschluss der Elemente

Sie haben sicherlich bemerkt, dass in gerenderten Dokumenten (Sie lesen gerade eins, sofern Sie nicht die XML-Version geöffnet haben) viele Elemente das gleiche Aussehen besitzen: Ein filename, ein literal und ein application haben die gleiche Typografie; das gleiche gilt für emphasis, firstterm und citetitle.

Was ist also der Sinn dieser verschiedenen Tags? Warum nicht nur ein paar, wie emphasis und literal, wenn sie sowieso gleich aussehen. Dafür gibt es zwei gute Gründe:

  • Erstens, wenn wir die meisten unserer Inline-Elemente als emphasis und literal kennzeichnen würden, ginge auch die Semantik verloren. Rufen Sie sich in Erinnerung, dass es im DocBook-XML nur um die Struktur und Semantik geht. firstterm und citetitle können genauso aussehen wie emphasis, sobald es gerendert wurde, aber sie sind nicht das Gleiche. Die XML-Quellen kennen diesen Unterschied, auch wenn dies nicht immer offensichtlich ist. Diese Information ist nützlich, und wir wollen diese nicht verlieren.

  • Des weitern, können wir unsere Stylesheets für jedes Element individuell anpassen. Sobald wir also entscheiden, dass ein firstterm anders als ein citetitle aussehen soll, können wir das tun - aber nur wenn sie tatsächlich als unterschiedliche Tags markiert wurden, nicht wenn beide emphasis's im XML-Quelltext sind.

Damit schließen wir die Abschnitte über DocBook ab. Mit dem bis hierher gezeigten Wissen, sollten Sie nun in der Lage sein, DocBook XML-Dokumente für das Firebird-Projekt zu erstellen. Wenn Sie einen dedizierten XML-Editor - was sehr ratsam ist - sollten Sie außerdem dessen Dokumentation konsultieren, um den Umgang hiermit zu lernen; Dies können wir mit diesem Leitfaden nicht abbilden.

Zurück: Bereiten Sie Ihr DocBook-Dokument vorFirebird Documentation IndexNach oben: Firebird Docwriting-AnleitungWeiter: Sprache und Stil
Firebird Documentation IndexFirebird Docwriting-Anleitung → Häufig verwendete Elemente