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:

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.

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:

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:

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

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.

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:

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:

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>[email protected]</email> to 
subscribe.

wird in der Ausgabe zu:

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

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.

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.

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, 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:

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:

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

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:

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.

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:

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

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:

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:

envar kennzeichnet eine Umgebungsvariable.

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 = mc², I really felt like a glass of liquid H₂O !

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.

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.

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.

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.

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).

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.

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.