Die Fibel für neue Mitarbeiter des FreeBSD-Dokumentationsprojekts
Zurück | Kapitel 4. SGML-Dokumente erstellen | Weiter

# 4.2. Die DocBook DTD

DocBook wurde ursprüglich von HaL Computer Systems and O'Reilly & Associates als DTD für das Erstellen von technischen Dokumenten entwickelt [1]. Seit 1998 wird es vom DocBook Technical Committee gewartet. DocBook ist sehr stark auf die Beschreibung von Inhalten, und nicht auf die Darstellung des Inhalts ausgerichtet. Damit steht es im Gegensatz zu LinuxDoc und HTML.

> Formelle und informelle Elemente: Einige Elemente der DocBook DTD sind in zwei Varianten vorhanden: formell und informell. Üblicherweise besitzt die formelle Variante einen Titel, dem der eigentliche Elementeninhalt folgt. Die informelle Variante hingegen hat keinen Titel.

Die DocBook DTD ist in der Ports-Sammlung im Port `textproc/docbook` enthalten und wird bei der Installation des Metaports `textproc/docproj` automatisch mitinstalliert.

## 4.2.1. Die FreeBSD-Erweiterungen

Für das FDP wurde die DocBook DTD durch das FreeBSD-Dokumentationsproject um zusätzliche Elemente erweitert, um damit präzisiere Auszeichnungsmöglichkeiten zur Verfügung zu haben. Sofern im folgenden FreeBSD-spezifische Elemente genutzt werden, wird explizit darauf hingewiesen werden.

Wenn nachfolgend im Text der Begriff “DocBook” verwendet wird, ist damit die durch das FDP erweiterte Version der DocBook DTD gemeint.

> Anmerkung: Die durch das FDP vorgenommenen Erweiterungen sind nicht FreeBSD-spezifisch. Sie wurden lediglich vorgenommen, da sie für die Arbeit des FDPs als nützlich erschienen. Für den Fall, das in den anderen *nix-Lagern (NetBSD, OpenBSD, Linux,...) Interesse daran besteht, gemeinsam eine Standarderweiterung für die DocBook DTD zu entwickeln, kann mit dem Documentation Engineering Team `<doceng@FreeBSD.org>` Verbindung aufgenommen werden.

Zum jetzigen Zeitpunkt sind die FreeBSD-Erweiterungen nicht Bestandteil der Ports-Sammlung. Sie werden im FreeBSD-CVS-Archiv (doc/share/sgml/freebsd.dtd) verwaltet.

## 4.2.2. Formelle Öffentliche Bezeichner

In Übereinstimmung mir der DocBook-Richtlinie zur Erstellung von Bezeichnern für DocBook-Erweiterungen lautet der Bezeichner der erweiterten FreeBSD-Variante:

    PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"

## 4.2.3. Die Struktur von DocBook-Dokumenten

DocBook erlaubt es, Dokumente auf verschiedene Weise zu strukturieren. Innerhalb des FDPs werden hauptsächlich zwei Arten von DocBook-Dokumenten verwendet: Buch und Artikel. Beide unterscheiden sich darin, dass ein Buch auf der obersten Ebene durch `<chapter>`-Elemente strukturiert wird. Sollte das noch nicht ausreichend sein, können die einzelnen Kapitel eines Buches mit Hilfe des Elementes `<part>` in Teile aufgespalten werden. Das Handbuch ist beispielsweise auf diese Weise aufgebaut.

Kapitel (`<chapter>`) können weiterhin in Unterkapitel unterteilt werden. Diese werden durch die Elemente `<sect1>` ausgezeichnet. Soll ein Unterkapitel selbst weitere Unterkapitel enthalten, kann das über das Element `<sect2>` geschehen. Diese Unterteilung kann bis zur Tiefe von fünf Unterkapiteln - über die Elemente `<sect3>`, `<sect4>` und `<sect5>` - fortgeführt werden. Der eigentliche Inhalt, um den es ja in dem Artikel oder Buch geht, wird unterhalb der hier genannten Elemente eingefügt.

Vom Aufbau her ist ein Artikel ist einfacher strukturiert als ein Buch. So kann ein Artikel beispielsweise keine Kapitel (`<chapter>`) enthalten. Stattdessen kann der Inhalt eines Artikels nur durch die schon bekannten `<sect`N`>`-Elemente in einen oder mehrere Abschnitte gegliedert werden. Überlegen Sie sich vor dem Schreiben eines Textes, ob der zu schreibende Text am besten als Buch oder als Artikel angelegt wird. Artikel eignen sich besser für Texte, die nicht in mehrere Kapitel aufgeteilt werden müssen und mit einem Umfang von ungefähr 20 bis 25 Seiten vergleichsweise kurz sind. Natürlich ist das nur eine Richtlinie. Bücher sind dementsprechend am besten für lange Texte geeignet, die sich sinnvoll in Kapitel unterteilen lassen und möglichweiser noch Anhänge und ähnliches enthalten können.

Alle Tutorien von FreeBSD sind als Artikel verfaßt, während hingegen die FreeBSD-FAQ und das FreeBSD-Handbuch als Bücher verfaßt wurden.

### 4.2.3.1. Bücher schreiben

Der Inhalt eines Buches wird in einem `<book>`-Element abgelegt. Neben dem Textteil des Buches kann dieses Element weitergehende Informationen über das Buch selbst, wie Meta-Informationen zum Erstellen eines Stichwortverzeichnisses oder zusätzliche Inhalte zum Erstellen einer Titelei, enthalten. Diese zusätzlichen Inhalte sollten in einem `<bookinfo>`-Element abgelegt werden.

Beispiel 4-20. Buchvorlage `<book>` mit `<bookinfo>`

    <book>
      <bookinfo>
        <title>Titel</title>
        <author>
          <firstname>Vorname</firstname>
          <surname>Nachname</surname>
          <affiliation>
            <address><email>E-Mail-Adresse</email></address>
          </affiliation>
        </author>

        <copyright>
          <year>1998</year>
          <holder role="mailto:E-Mail-Adresse">Vollständiger Name</holder>
        </copyright>

        <releaseinfo>$FreeBSD$</releaseinfo>

        <abstract>
          <para>Kurze Zusammenfassung des Buchinhaltes.</para>
        </abstract>
      </bookinfo>

      ...

    </book>

### 4.2.3.2. Artikel schreiben

Der Inhalt eines Artikels wird in einem `<article>`-Element abgelegt. Neben dem Textteil kann dieses Element weitere Teile, wie Meta-Informationen zum Erstellen eines Stichwortverzeichnisses oder zusätzliche Inhalte zum Erstellen einer Titelei, enthalten. Analog zu einem Buch, sollten diese Informationen in einem `<articleinfo>`-Element abgelegt werden.

Beispiel 4-21. Artikelvorlage `<article>` mit `<articleinfo>`

    <article>
      <articleinfo>
        <title>Titel</title>

        <author>
          <firstname>Vorname</firstname>
          <surname>Nachname</surname>
          <affiliation>
            <address><email>E-Mail-Adresse</email></address>
          </affiliation>
        </author>

        <copyright>
          <year>1998</year>
          <holder role="mailto:E-Mail-Adresse">Vollständiger Name</holder>
        </copyright>

        <releaseinfo>$FreeBSD$</releaseinfo>

        <abstract>
          <para>Kurze Zusammenfassung des Artikelinhalts.</para>
        </abstract>
      </articleinfo>

      ...

    </article>

### 4.2.3.3. Kapitel

Kapitel werden mit dem `<chapter>`-Element angelegt und müssen ein `<title>`-Element enthalten. Verwendet werden können sie nur in Büchern.

Beispiel 4-22. Ein einfaches Kapitel

    <chapter>
      <title>Kapitelüberschrift</title>

      ...
    </chapter>

Kapitel können nicht leer sein. Nebem einem `<title>`-Element müssen sie weiteren Inhalt beinhalten. Falls ein leeres Kapitel benötig wird, kann dies durch das Einfügen eines leeren Absatzes (`<para>`) erreicht werden.

Beispiel 4-23. Ein leeres Kapitel

    <chapter>
      <title>Das ist ein leeres Kapitel</title>

      <para></para>
    </chapter>

### 4.2.3.4. Unterkapitel

Bücher werden auf der obersten Gliederungsebene durch `<chapter>`-Elemente in Kapitel unterteilt. Eine weitergehende Untergliederung kann durch das Anlegen von Unterkapiteln erreicht werden. Im Gegensatz zu Kapiteln, die durch `<chapter>`-Elemente ausgezeichnet werden, erfolgt die Auszeichnung von Unterkapitel mit dem Element `<sect`n`>`. Das `n` in Elementnamen trifft eine Aussage über die Gliederungstiefe, auf der sich das Unterkapitel befindet. Ein `<sect1>`-Element kann mehrere Elemente vom Typ `<sect2>` enthalten, die die Unterkapitel der nächsten Gliederungsebene darstellen. `<sect5>` ist das letzte Element, das auf diese Art zur Gliederung eingesetzt werden kann.

Beispiel 4-24. Unterkapitel

    <chapter>
      <title>Ein Beispielkapitel</title>

      <para>Ein beliebiger Text.</para>

      <sect1>
        <title>Erster Abschnitt (1.1)</title>

        ...
      </sect1>

      <sect1>
        <title>Zweiter Abschnitt (1.2)</title>

        <sect2>
          <title>Erster Unterabschnitt (1.2.1)</title>

          <sect3>
            <title>Erster Unterunterabschnitt (1.2.1.1)</title>

             ...
          </sect3>
        </sect2>

        <sect2>
          <title>Zweiter Unterabschnitt (1.2.2)</title>

          ...
        </sect2>
      </sect1>
    </chapter>

> Anmerkung: Die Unterkapitel dieses Beispiels wurden zu Demonstrationszwecken manuell durchnummeriert. In “normalen” Dokumenten wird diese Aufgabe von den Stylesheets übernommen.

### 4.2.3.5. Bücher mittels `<part>` unterteilen

In den Fällen, in denen die Unteilung eines Buches in Kapitel nicht ausreichend ist, können mehrere Kapitel mit dem Element `<part>` zu einem Teil zusammengefasst werden.

    <part>
      <title>Einführung</title>

      <chapter>
        <title>Überblick</title>

         ...
      </chapter>

      <chapter>
        <title>Was ist FreeBSD?</title>

        ...
      </chapter>

      <chapter>
        <title>Die Geschichte von FreeBSD</title>

        ...
      </chapter>
    </part>

## 4.2.4. Blockelemente

### 4.2.4.1. Absätze

DocBook kennt drei Arten von Absätzen: Absätze mit Überschrift (`<formalpara>`), normale Absätze (`<para>`) und einfache Absätze (`<simpara>`).

Normale Absätze und einfache Absätze unterscheiden sich dadurch, dass innerhalb von `<para>` Blockelemente erlaubt sind, innerhalb von `<simpara>` hingegen nicht. Es ist empfehlenswert, `<para>` den Vorzug zu geben.

Beispiel 4-25. Absatz mit `<para>`

    <para>Das ist ein Absatz. Absätze können fast jedes andere
      Element aufnehmen.</para>

Darstellung:

Das ist ein Absatz. Absätze können fast jedes andere Element aufnehmen.

### 4.2.4.2. Blockzitate

Blockzitate sind textlich umfangreichere Zitate aus einem anderen Text, die nicht innerhalb des aktuellen Absatzes angezeigt werden sollen. Wahlweise können Blockzitate eine Überschrift haben und die Zitatquelle nennen.

Beispiel 4-26. `<blockquote>`

    <para>Ein Auszug aus dem Grundgesetz:</para>

    <blockquote>
      <title>Menschenw&uuml;rde; Grundrechtsbindung der staatlichen Gewalt</title>

      <attribution>Aus dem Grundgesetz</attribution>

      <orderedlist>
        <listitem>
          <para>Die W&uuml;rde des Menschen ist unantastbar. Sie zu achten
            und zu sch&uuml;tzen ist Verpflichtung aller staatlichen
            Gewalten.</para>
        </listitem>
        <listitem>
          <para>Das Deutsche Volk bekennt sich darum zu unverletzlichen
            und unver&auml;u&szlig;erlichen Menschenrechten als Grundlage jeder
            menschlichen Gemeinschaft, des Friedens und der
            Gerechtigkeit in der Welt.</para>
        </listitem>
        <listitem>
          <para>Die nachfolgenden Grundrechte binden Gesetzgebung,
            vollziehende Gewalt und Rechtsprechung als
            unmittelbar geltendes Recht.</para>
        </listitem>
      </orderedlist>
    </blockquote>

Darstellung:

Menschenwürde; Grundrechtsbindung der staatlichen Gewalt

1. Die Würde des Menschen ist unantastbar. Sie zu achten und zu schützen ist Verpflichtung aller staatlichen Gewalten.

2. Das Deutsche Volk bekennt sich darum zu unverletzlichen und unveräußerlichen Menschenrechten als Grundlage jeder menschlichen Gemeinschaft, des Friedens und der Gerechtigkeit in der Welt.

3. Die nachfolgenden Grundrechte binden Gesetzgebung, vollziehende Gewalt und Rechtsprechung als unmittelbar geltendes Recht.

--Aus dem Grundgesetz |

### 4.2.4.3. Tipps, Anmerkungen, Warnungen, wichtige Informationen und Randbemerkungen

In bestimmten Fällen kann es nützlich sein, dem Leser zusätzliche Informationen zu geben, die sich vom Haupttext abheben, damit der Leser sie besser wahrnimmt. Abhängig von der Art der Information, können solche Stellen mit einem der Elemente `<tip>` (für Tipps), `<note>` (für Anmerkungen), `<warning>` (für Warnungen), `<caution>` (für besonders ernstzunehmende Warnungen) und `<important>` (für wichtige Anmerkungen) ausgezeichnet werden. Trifft keines dieser Element für die auszuzeichnende Stelle zu, sollte diese mit dem Element `<sidebar>` ausgezeichnet werden.

Da die richtige Einordnung einer auszuzeichnenden Textstelle nicht immer leicht zu treffen ist, werden in der DocBook-Dokumentation folgende Empfehlungen gegeben:

- Eine Anmerkung (`<note>`) ist eine Information, die von jedem Leser beachtet werden sollte.

- Eine wichtige Anmerkung (`<important>`) eine Variation einer Anmerkung.

- Eine Warnung (`<warning>`) betrifft einen möglichen Hardwareschaden oder weist auf eine Gefahr für Leib und Leben hin.

- Eine besonders ernstzunehmende Warnung (`<caution>`) betrifft einen möglichen Datenverlust oder Softwareschaden.

Beispiel 4-27. `<warning>`

    <warning>
      <para>Wenn Sie FreeBSD auf Ihrer Festplatte installieren,
        kann es sein, da&szlig; Sie Windows nie mehr benutzen wollen.</para>
    </warning>

Eine Warnung wird wie folgt dargestellt:

> Warnung: Wenn Sie FreeBSD auf Ihrer Festplatte installieren, kann es sein, dass Sie Windows nie mehr benutzen wollen.

### 4.2.4.4. Listen und Handlungsanweisungen

Listen sind ein oft gebrauchtes Hilfsmittel, wenn es darum geht, Informationen für den Benutzer übersichtlich darzustellen oder eine Abfolge von Arbeitsschritten zu beschreiben, die notwendig sind, um ein bestimmtes Ziel zu erreichen. Zur Auszeichnung von Listen stellt DocBook die Elemente `<itemizedlist>`, `<orderedlist>` und `<procedure>` zur Verfügung.[2].

`<itemizedlist>` und `<orderedlist>` ähneln sehr stark ihren HTML-Gegenstücken `<ul>` und `<ol>`. Beide Listenarten müssen mindestens ein Element `<listitem>` enthalten. Das `<listitem>` Element muss mindestens ein weiteres Blockelement enthalten.

`<procedure>` unterscheidet sich ein wenig von den vorhergehenden. Es enthält `<step>`-Elemente, die wiederum `<step>`- oder `<substel>`-Elemente enthalten können. Ein `<step>`-Element kann nur Blockelemente aufnehmen.

Beispiel 4-28. `<itemizedlist>`, `<orderedlist>` und `<procedure>`

    <itemizedlist>
      <listitem>
        <para>Das ist das erste Listenelement.</para>
      </listitem>

      <listitem>
        <para>Das ist das zweite Listenelement.</para>
      </listitem>
    </itemizedlist>

    <orderedlist>
      <listitem>
        <para>Das ist das erste Aufzählungselement.</para>
      </listitem>

      <listitem>
        <para>Das ist das zweite Aufzählungselement.</para>
      </listitem>
    </orderedlist>

    <procedure>
      <step>
        <para>Machen Sie zuerst dies.</para>
      </step>

      <step>
        <para>Und dann machen Sie das..</para>
      </step>

      <step>
        <para>Und jetzt noch das...</para>
      </step>
    </procedure>

Darstellung:

- Das ist das erste Listenelement.

- Das ist das zweite Listenelement.

1. Das ist das erste Aufzählungselement.

2. Das ist das zweite Aufzählungselement.

1. Machen Sie zuerst dies.

2. Und dann machen Sie das..

3. Und jetzt noch das...

### 4.2.4.5. Dateiinhalte auszeichnen

Technische Dokumente enthalten oft auch Konfigurationsbeispiele oder Quellcodeschnipsel. Zur Auszeichnung dieser Inhalte, stellt Docbook das Element `<programmlisting>` zur Verfügung. Im Gegensatz zu anderen DocBook-Elementen wird der Elementinhalt von `<programmlisting>` nicht normalisiert, das heißt, dass alle Leerzeichen, Tabulatoren und Zeilenumbrüche unverändert übernommen werden. Aus diesem Grund ist es unter anderem wichtig, dass sich der öffende Tag in der selben Zeile wie der Anfang des darzustellenden Textes befindet. Gleiches gilt für den schließenden Tag: Er muss sich am Ende der letzten Zeile befinden. Wird das nicht beachtet, kann es sein, dass unerwartete Leerzeichen und Leerzeilen in der Ausgabe auftauchen.

Beispiel 4-29. `<programlisting>`

    <para>Am Ende sollte Ihr Programm wie folgt
      aussehen:</para>

    <programlisting>#include &lt;stdio.h&gt;

    int
    main(void)
    {
        printf("Hallo Welt!\n");
    }</programlisting>

Die spitzen Klammern der `#include`-Anweisung können nicht direkt verwendet werden, sondern müssen über ihre Entitäten eingebunden werden.

Darstellung:

Am Ende sollte Ihr Programm wie folgt aussehen:

    #include <stdio.h>

    int
    main(void)
    {
        printf("Hallo Welt!\n");
    }

### 4.2.4.6. Textanmerkungen

Textanmerkungen[3] sind ein Mechanismus, um auf bestimmte Stellen in einem vorhergehenden Beispiel oder Text zu verweisen.

Um solche Verweise anzulegen, müssen die betreffenden Stellen in den Beispielen (`<programlisting>`, `<literallayout>`, ...) mit `<co>`-Elementen markiert werden, wobei jedes Element ein eindeutiges `id`-Attribut besitzen muss. Anschließend sollte ein `<calloutlist>`-Element eingefügt werden, dessen Elemente sich auf die `<co>`-Elemente des Beispiels beziehen und die jeweiligen Anmerkungen enthalten.

Beispiel 4-30. Das `<co>`- und das `<calloutlist>`-Element

    <para>Am Ende sollte Ihr Programm wie folgt
      aussehen:</para>

    <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include">

    int <co id="co-ex-return">
    main(void)
    {
        printf("Hallo Welt\n"); <co id="co-ex-printf">
    }</programlisting>

    <calloutlist>
      <callout arearefs="co-ex-include">
        <para>Bindet die Headerdatei <filename>stdio.h</filename> ein.</para>
      </callout>

      <callout arearefs="co-ex-return">
        <para>Bestimmt den Typ des Rückgabewertes von <function>main()</function>.</para>
      </callout>

      <callout arearefs="co-ex-printf">
        <para>Ruft die Funktion <function>printf()</function> auf, die
          <literal>Hallo Welt!</literal> auf der Standardausgabe ausgibt</para>
      </callout>
    </calloutlist>

Darstellung:

Am Ende sollte Ihr Programm wie folgt aussehen:

    #include &lt;stdio.h&gt;

    int
    main(void)
    {
        printf("Hallo Welt\n");
    }

  Bindet die Headerdatei `stdio.h` ein.
  Bestimmt den Typ des Rückgabewertes von `main()`.
  Ruft die Funktion `printf()` auf, die `Hallo Welt!` auf der Standardausgabe ausgibt

### 4.2.4.7. Tabellen

Im Gegensatz zu HTML ist es nicht notwendig, Tabellen zu Layoutzwecken einzusetzen, da die Layoutaufgabe von den Stylesheets übernommen wird. Stattdessen sollten Tabellen nur für die Auszeichnung von Daten in Tabellenform genutzt werden.

Vereinfacht betrachtet (für Details sollte die DocBook-Dokumentation zu Rate gezogen werden) besteht eine Tabelle, die entweder als formelle oder als informelle Tabelle angelegt werden kann, aus einem `<table>`-Element. Dieses Element selbst beinhaltet mindestens ein Element `<tgroup>`, das über ein Attribut die Spaltenanzahl der Tabelle bestimmt. Innerhalb des Elementes `<tgroup>` kann sich ein Element `<thead>` mit den Spaltenüberschriften und ein Element `<tbody>` mit dem eigentlichen Tabelleninhalt befinden. Beide Elemente beinhalten `<row>`-Elemente, die wiederum `<entry>`-Elemente beinhalten. Jedes `<entry>`-Element stellt eine einzelne Tabellenzelle dar.

Beispiel 4-31. Tabellen mittels `<informaltable>` auszeichnen

    <informaltable pgwide="1">
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Spaltenüberschrift 1</entry>
            <entry>Spaltenüberschrift 2</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>Zeile 1, Spalte 1</entry>
            <entry>Zeile 1, Spalte 2</entry>
          </row>

          <row>
            <entry>Zeile 2, Spalte 1</entry>
            <entry>Zeile 2, Spalte 2</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

Darstellung:

Spaltenüberschrift 1 | Spaltenüberschrift 2
--- | ---
Zeile 1, Spalte 1 | Zeile 1, Spalte 2
Zeile 2, Spalte 1 | Zeile 2, Spalte 2

Verwenden Sie stets das Attribut `pgwide` mit dem Wert `1`, wenn Sie das Element `<informaltable>` benutzen. Ein Bug des Internet Explorers verhindert ansonsten die korrekte Darstellung dieser Tabellen.

Soll die Tabelle keinen Rand haben, kann das Attribut `frame` mit dem Wert `none` dem Element `<informaltable>` hinzugefügt werden (`<informaltable frame="none">`)).

Beispiel 4-32. Tabelle mit Attribut `frame="none"`

Darstellung:

Spaltenüberschrift 1 | Spaltenüberschrift 2
--- | ---
Zeile 1, Spalte 1 | Zeile 1, Spalte 2
Zeile 2, Spalte 1 | Zeile 2, Spalte 2

### 4.2.4.8. Beispiele für den Leser

Oft gilt es, für dem Benutzer Beispiele zu geben, die er dann selber nachvollziehen soll. Meist handelt es sich dabei um interaktive Dialoge zwischen Mensch und Maschine: Der Benutzer gibt einen Befehl ein und erhält eine Antwort vom System. Ein Satz von speziellen Elementen und Entitäten unterstützt den Autor bei der Auszeichnung solcher Textstellen:

`<screen>`

  Gedacht zur Auszeichnung von Bildschirminhalten. Im Unterschied zu anderen Elementen werden Leerzeichen innerhalb des Elementes `<screen>` unverändert übernommen.

`<prompt>`, `&prompt.root;` und `&prompt.user;`

  Eingabeaufforderungen des Rechners (Betriebssysten, Shell oder Anwendung) sind ein häufig auftretender Teil dessen, was der Benutzer auf dem Bildschirm zu sehen bekommt. Sie sollten mit `<prompt>` ausgezeichnet werden.

  Ein Spezialfall sind die beiden Eingabeaufforderungen der Shell für normale Benutzer und den Superuser `root`. Jedesmal wenn auf eine von diesen beiden Nutzerrollen hingewiesen werden soll, sollte entweder `&prompt.root;` oder `&prompt.user;` eingesetzt werden. Beide Entitäten können auch außerhalb von `<screen>` verwendet werden.

  > Anmerkung: `&prompt.root;` und `&prompt.user;` sind FreeBSD-spezifische Erweiterungen der DocBook DTD und nicht in der originalen DocBook DTD enthalten.

`<userinput>`

  Das Element `<userinput>` ist für die Auszeichnung von Benutzereingaben gedacht.

Beispiel 4-33. `<screen>`, `<prompt>` und `<userinput>`

    <screen>&prompt.user; <userinput>ls -1</userinput>
    foo1
    foo2
    foo3
    &prompt.user; <userinput>ls -1 | grep foo2</userinput>
    foo2
    &prompt.user; <userinput>su</userinput>
    <prompt>Password: </prompt>
    &prompt.root; <userinput>cat foo2</userinput>
    This is the file called 'foo2'</screen>

Darstellung:

    % ls -1
    foo1
    foo2
    foo3
    % ls -1 | grep foo2
    foo2
    % su
    Password:
    # cat foo2
    This is the file called 'foo2'

> Anmerkung: Obgleich der Inhalt der Datei `foo2` in dem obigen Beispiel angezeigt wird, sollte dieser nicht mit `<programlisting>` ausgezeichnet werden. Vielmehr sollte `<programlisting>` einzig und allein für die Darstellung von Dateifragmenten außerhalb von Benutzeraktionen gewählt werden.

## 4.2.5. Flußelemente

### 4.2.5.1. Hervorhebungen

Wenn es darum geht bestimmte Wörter oder Textstellen hervorzuheben, sollte dafür das Element `<emphasis>` verwendet werden. Das so ausgezeichnete Text wird dann kursiv oder fett dargestellt; im Falle einer Sprachausgabe würde es anders betont werden.

Im Gegensatz zu den HTML mit seinen Elementen `<b>` und `<i>`, kennt DocBook keinen Weg, um diese Darstellung zu ändern[4]. Handelt es sich bei dem darzustellenden um eine wichtige Information, kann alternativ `<important>` verwendet werden.

Beispiel 4-34. Das Element `<emphasis>`

    <para>FreeBSD ist zweifelslos <emphasis>das</emphasis> führende
      Unix-artige Bestriebssystem für die Intel-Plattform.</para>

Darstellung:

FreeBSD ist zweifelslos das führende Unix-artige Bestriebssystem für die Intel-Plattform.

### 4.2.5.2. Zitate

Um einen Auszug aus einer anderen Quelle zu zitieren oder kenntlich zu machen, dass eine bestimmte Wendung im übertragenen Sinne zu verstehen ist, kann der betreffende Text mit Hilfe des Elementes `<quote>` ausgezeichnet werden. Innerhalb von `<quote>` können die meisten der normalerweise zur Verfügung stehenden Elemente genutzt werden.

Beispiel 4-35. Richtig zitieren

    <para>Es sollte immer sichergestellt werden, dass die Suche die Grenzen
      zwischen <quote>lokaler und öffentlicher Administration</quote>
      (RFC 1535) einhält.</para>

Darstellung:

Es sollte immer sichergestellt werden, das die Suche die Grenzen zwischen “lokaler und öffentlicher Administration” (RFC 1535) einhält.

### 4.2.5.3. Tasten, Maustasten und Tastenkombinationen

Das Element `<keycap>` beschreibt eine bestimmte Taste der Tastatur. Für die Auszeichnung von Maustasten steht analog das Element `<mousebutton>` zur Verfügung. Mit Hilfe von `<keycombo>` können beliebige Tasten- und Maustastenkombinationen beschrieben werden.

Das Element `<keycombo>` besitzt ein Attribut `action`, dem einer der Werte `click`, `double-click`, `other`, `press`, `seq` oder `simul` zugewiesen werden kann. Die letzten beiden Werte deuten an, dass die genannte Kombination nacheinander oder gleichzeitig gedrückt werden soll. Die Stylesheets fügen zwischen die einzelnen Unterelemente von `<keycombo>` “+”-Zeichen ein.

Beispiel 4-36. Tasten, Maustasten und Tastenkombinationen

Diese Eingaben zeichnen Sie wie folgt aus:

    <para>Mit der Tastenkombination <keycombo action="simul"><keycap>Alt</keycap>
      <keycap>F1</keycap></keycombo> kann auf die zweite virtuelle Konsole
      umgeschaltet werden.</para>

    <para>Um <command>vi</command> zu beenden, ohne die Änderungen zu
      speichern, muss <keycombo action="seq"><keycap>Esc</keycap>
      <keycap>:</keycap><keycap>q</keycap><keycap>!</keycap>
      </keycombo> eingegeben werden.</para>

    <para>Der Fenstermanager ist so konfiguriert, dass mittels
      <keycombo action="simul"><keycap>Alt</keycap>
      <mousebutton>rechter Maustaste</mousebutton> </keycombo>
       Fenster verschoben werden können.</para>

Darstellung:

Mit der Tastenkombination Alt+F1 kann auf die zweite virtuelle Konsole umgeschaltet werden.

Um `vi` zu beenden, ohne die Änderungen zu speichern, muss Esc : q ! eingegeben werden.

Der Fenstermanager ist so konfiguriert, dass mittels Alt+rechter Maustaste Fenster verschoben werden können.

### 4.2.5.4. Anwendungen, Befehle, Optionen und Hilfeseiten

Oft besteht die Notwendigkeit auf bestimmte Anwendungen und Befehle zu verweisen. Der Unterschied zwischen einer Anwendung und einem Befehl liegt darin, dass eine Anwendung ein einzelnes oder eine Gruppe von Programmen ist, mit denen eine bestimmte Aufgabe erledigt werden kann. Ein Befehl hingegen ist der Name eines Programmes, dass der Benutzer aufrufen kann[5].

Desweiteren kann es auch vorkommen, dass die von einem Programm (in einem bestimmten Fall) akzeptierten Optionen genannt werden müssen.

Schlußendlich ist es oft gewünscht, zu einem Befehl dessen Abschnitt der Manualseiten im Unix-üblichen Stil “Befehl(Zahl)” anzugeben.

Anwendungsnamen können mit `<application>` ausgezeichnet werden.

Befehle können zusammen mit der betreffenden Hilfeseite über das DocBook-Element `<citerefentry>` ausgezeichnet werden. `<citerefentry>` muss zwei weitere Elemente enthalten: `<refentrytitle>`, für den Befehlsnamen, und `<manvolnum>`, für die Kategorie der Hilfeseite.

Diese Art auf Befehle zu verweisen kann sehr ermüdent sein. Daher gibt es einen Satz von Allgemeinen Entitäten, der diese Arbeit erleichtert. Er ist in der Datei `doc/share/sgml/man-refs.ent` enhalten und kann über den folgenden Bezeichner eingebunden werden:

    PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

Jede Entität in dieser Datei ist wie folgt aufgebaut: `&man.`Hilfeseite`.`Kategorie`;`.

Der Anfang eines Dokumentes, das diese Entitäten einbindet, könnte so aussehen:

    <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
    <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
    %man; ... ]>

Um Befehle innerhalb des Fließtextes auszuzeichen, kann das Element `<command>` genutzt werden. Die Optionen eines Befehles können mit Hilfe von `<option>` ausgezeichnet werden.

Wenn man sich mehrmals hintereinander auf den gleichen Befehl bezieht, sollte man beim ersten Auftreten die Notation `&man.`command`.`section`;` verwenden. Für alle folgenden Referenzen sollte hingegen `<command>` verwendet werden. Dadurch verbessert sich das Erscheinungsbild, insbesondere von HTML, deutlich.

Die Unterscheidung zwischen `<command>` und `<application>` kann schwer sein, und manchmal ist die Entscheidung, welches Element das richtige ist, nicht leicht. Das folgende Beispiel soll diese Unterscheidung erleichtern.

Beispiel 4-37. Anwendungen, Befehle und Optionen

    <para><application>Sendmail</application> ist der verbreitetste
      UNIX-Mailserver.</para>

    <para><application>Sendmail</application> besteht aus den Programmen
      <citerefentry>
        <refentrytitle>sendmail</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>, &man.mailq.1;, und &man.newaliases.1;.</para>

    <para>Mittels der Option <option>-bp</option> kann
      <citerefentry><refentrytitle>sendmail</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry> den Status der Mailwarteschlange ausgeben.
      Der Status der Mailwarteschlange kann durch den Befehl
      <command>sendmail -bp</command> überprüft werden.</para>

Darstellung:

Sendmail ist der verbreitetste UNIX-Mailserver.

Sendmail besteht aus den Programmen sendmail(8), mailq(1) sowie newaliases(1).

Mittels der Option `-bp` kann sendmail(8) den Status der Mailwarteschlange ausgeben. Der Status der Mailwarteschlange kann durch den Befehl `sendmail -bp` überprüft werden.

> Anmerkung: Die Schreibweise `&man.`Hilfeseite`.`Kategorie`;` ist leichter lesbar.

### 4.2.5.5. Dateien, Verzeichnisse und Erweiterungen

Immer wenn in einem Text der Name einer Datei, eines Verzeichnisses oder eine Dateierweiterung vorkommt, sollte die betreffende Stelle mit dem Element `<filename>` ausgezeichnet werden.

Beispiel 4-38. Das Element `<filename>`

    <para>Die SGML-Quellen des
            englischen Handbuches befinden sich im Verzeichnis
            <filename
            class="directory">/usr/doc/en/handbook/</filename>. In
            diesem Verzeichnis befindet sich eine Datei
            <filename>handbook.sgml</filename>. Desweiteren sollte
            sich eine Datei mit dem Namen
            <filenname>Makefile</filename> zusammen mit mehreren
            Dateien mit der Endung <filename>.ent</filename> in diesem
            Verzeichnis befinden.</para>

Darstellung:

Die SGML-Quellen des englischen Handbuches befinden sich im Verzeichnis `/usr/doc/en/handbook/`. In diesem Verzeichnis befindet sich eine Datei `handbook.sgml`. Desweiteren sollte sich eine Datei mit dem Namen `Makefile` zusammen mit mehreren Dateien mit der Endung `.ent` in diesem Verzeichnis befinden.

### 4.2.5.6. Portnamen

> FreeBSD-Erweiterung: Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung für DocBook und sind nicht in der originalen DocBook DTD enthalten.

An einigen Stellen ist es notwendig, den Namen eines Ports aus FreeBSDs Ports-Sammlung in Dokumenten zu verwenden. In diesem Fall sollte ebenfalls das Element `<filename>` eingesetzt werden, dabei aber dem Element das Attribut `role` mit dem Wert `package` zugewiesen werden. Da die Ports-Sammlung an jeder beliebigen Stelle im Dateisystem installiert werden kann, sollte `<filename>` nur die Kategorie und den Namen des Ports enthalten, aber nicht das Verzeichnis `/usr/ports`.

Beispiel 4-39. Portsnamen und das Element `<filename>`

    <para>Wenn Sie Ihr Netz und dessen Datenverkehr analysieren
      möchten, dann installieren Sie bitte den Port <filename
      role="package">net/ethereal</filename>.</para>

Darstellung:

Wenn Sie Ihr Netz und dessen Datenverkehr analysieren möchten, dann installieren Sie bitte den Port `net/ethereal`.

### 4.2.5.7. Gerätedateien unterhalb von `/dev`

> FreeBSD-Erweiterung: Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung für DocBook und sind nicht in der originalen DocBook DTD enthalten.

Wird in einem Dokument Bezug auf Gerätedateien unterhalb von `dev` genommen, dann gibt es zwei Möglichkeiten diese auszuzeichnen. Zum einen kann man sich auf das Gerät beziehen, so wie es unter `/dev` zu finden ist, und zum anderen kann man sich auf den Gerätenamen beziehen, wie es innerhalb des Kerns verwendet wird. Für letztere Möglichkeit sollte das Element `<devicename>` genutzt werden.

Allerdings besteht nicht immer diese Wahlmöglichkeit. Einige Geräte, wie zum Beispiel Netzwerkkartenm haben keinen Eintrag unter `/dev` oder werden anders dargestellt.

Beispiel 4-40. Gerätenamen per `<devicename>` auszeichnen

    <para>Unter FreeBSD wird die serielle Datenübertragung über
      <devicename>sio</devicename> abgewickelt, das unterhalb von
      <filename>/dev</filename> eine Reihe von Einträgen anlegt.
      Zu diesen Einträgen behören beispielsweise
      <filename>/dev/ttyd0</filename> und
      <filename>/dev/cuaa0</filename>.</para>

      <para>Andererseits erscheinen Geräte wie beispielsweise
        <devicename>ed0</devicename> nicht unterhalb von
        <filename>/dev</filename>.</para>

      <para>Unter MS-DOS wird das erste Diskettelaufwerk als
        <devicename>a:</devicename> bezeichnet.  FreeBSD
         bezeichnet es als <filename>/dev/fd0</filename>.</para>

Darstellung:

Unter FreeBSD wird die serielle Datenübertragung über `sio` abgewickelt, das unterhalb von `/dev` eine Reihe von Einträgen anlegt. Zu diesen Einträgen behören beispielsweise `/dev/ttyd0` und `/dev/cuaa0`.

Andererseits erscheinen Geräte wie beispielsweise `ed0` nicht unterhalb von `/dev`.

Unter MS-DOS wird das erste Diskettelaufwerk als `a:` bezeichnet. FreeBSD bezeichnet es als `/dev/fd0`.

### 4.2.5.8. Rechner, Domains, IP-Adressen und mehr

> FreeBSD-Erweiterung: Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung für DocBook und sind nicht in der originalen DocBook DTD enthalten.

Bezeichner für Rechner können in Abhängigkeit der Bezeichnungsweise auf verschiedene Art und Weise ausgezeichnet werden. Gemeinsam ist allen, dass sie das Element `<hostid>` benutzen. Über das Attribut `role` wird die Art des Bezeichners genauer bestimmt.

Kein Rollenattribut oder `role="hostname"`

  Ohne Rollenattribut stellt der umschlossene Text einen normlen Rechnernamen wie `freefall` oder `wcarchive` dar. Wenn es gewünscht ist, kann mittels `role="hostname"` explizit angegeben werden, dass es sich um einen Rechnernamen handelt.

`role="domainname"`

  Ein Domainname wie `FreeBSD.org` oder `ngo.org.uk`. Er enthält keinen Rechnernamen.

`role="fqdn"`

  Vollqualifizierter Domainname wie `www.FreeBSD.org`. Enthält sowohl einen Domainnamen als auch einen Rechnernamen.

`role="ipaddr"`

  Eine IP-Adresse, meistens als durch Doppelpunkte getrenntes Tupel von vier Zahlen dargestellt.

`role="ip6addr"`

  Eine IPv6-Adresse.

`role="netmask"`

  Eine Netzwerkmaske, dargestellt als ein durch Doppelpunkte getrenntes Vierzahlentupel, einer Hexzahl oder als ein `/`, dem eine Zahl folgt.

`role="mac"`

  Eine MAC-Adresse, dargestellt durch zweistellige Hexzahlen, die durch Doppelpunkte getrennt sind.

Beispiel 4-41. `role` und `<hostid>`

    <para>Der lokale Rechner kann immer über den Namen
      <hostid>localhost</hostid>  angesprochen werden, dem immer
      die IP-Adresse
      <hostid role="ipaddr">127.0.0.1</hostid> zugeordnet ist.</para>

      <para>Zur Domain <hostid role="domainname">FreeBSD.org</hostid>
        gehören verschiedene Rechner, inklusive <hostid
        role="fqdn">freefall.FreeBSD.org</hostid> und <hostid
        role="fqdn">pointyhat.FreeBSD.org</hostid>.</para>

      <para>Wenn eine IP-Adresse einer Netzwerkkarte zugeordnet wird,
        was mit der Hilfe von <command>ifconfig</command> geschieht,
        sollte <emphasis>immer</emphasis> die Netzmaske
        <hostid role="netmask">255.255.255.255</hostid>, die auch
        hexadezimal als <hostid role="netmask">0xffffffff</hostid>
        abgegeben werden kann, benutzt werden.</para>

      <para>Die MAC-Adresse ist für jede existierende Netzwerkkarte
        auf der Welt eindeutig. Eine typische MAC-Adresse ist
        beispielsweise <hostid
        role="mac">08:00:20:87:ef:d0</hostid>.</para>

Darstellung:

Der lokale Rechner kann immer über den Namen `localhost` angesprochen werden, dem immer die IP-Adresse `127.0.0.1` zugeordnet ist.

Zur Domain `FreeBSD.org` gehören verschieden Rechner, inklusive `freefall.FreeBSD.org` und `bento.FreeBSD.org`.

Wenn eine IP-Adresse einer Netzwerkkarte zugeordnet wird, was mit der Hilfe von `ifconfig` geschieht, sollte immer die Netzmaske `255.255.255.255`, die auch hexadezimal als `0xffffffff` abgegeben werden kann, benutzt werden.

Die MAC-Adresse ist für jede existierende Netzwerkkarte auf der Welt eindeutig. Eine typische MAC-Adresse ist beispielsweise `08:00:20:87:ef:d0`.

### 4.2.5.9. Benutzernamen

> FreeBSD-Erweiterung: Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung für DocBook und sind nicht in der originalen DocBook DTD enthalten.

Namen von Benutzern, wie `root` oder `bib`, können mit dem Element `<username>` ausgezeichnet werden.

Beispiel 4-42. Das Element `<username>`

    <para>Für die meisten Administrationsaufgaben müssen
        Sie als <username>root</username> angemeldet sein.</para>

Darstellung:

Für die meisten Administrationsaufgaben müssen Sie als `root` angemeldet sein.

### 4.2.5.10. Beschreibung von `Makefile`s

> FreeBSD-Erweiterung: Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung für DocBook und sind nicht in der originalen DocBook DTD enthalten.

Zur Beschreibung von Teilen einer Makedatei stehen die beiden Elemente `<marketarget>` und `<makevar>` zur Verfügung. `<maketarget>` bezeichnet ein Ziel eines `Makefile`s, das als Parameter beim Aufruf von `make` angegeben werden kann. `<makevar>` hingegen bezeichnet eine Variable, die entweder in einem `Makefile` definiert oder `make` auf der Befehlszeile übergeben werden kann, um so den Bauprozess zu beeinflussen.

Beispiel 4-43. `<maketarget>` und `<makevar>`

    <para>Zwei übliche Ziele in einem <filename>Makefile</filename>
      sind <maketarget>all</maketarget> und
      <maketarget>clean</maketarget>.</para>

    <para>Üblicherweise wird, wenn das Ziel <maketarget>all</maketarget>
      aufgerufen wird, die gesamte Anwendung neu erstellt. Der Aufruf
      des Zieles <maketarget>clean</maketarget> veranlaßt das
      Löschen aller temporären Dateien (zum Beispiel
      <filename>.o</filename>), die während der Übersetzung erzeugt
      wurden.</para>

    <para>Das genaue Verhalten von <maketarget>clean</maketarget>
      kann von einer Reihe von Variablen beeinflußt werden.
      Stellvertretend seien hier <makevar>CLOBBER</makevar> und
      <makevar>RECURSE</makevar> genannt.</para>

Darstellung:

Zwei übliche Ziele in einem `Makefile` sind `all` und `clean`.

Üblicherweise wird, wenn das Ziel `all` aufgerufen wird, die gesamte Anwendung neu erstellt. Der Aufruf des Zieles `clean` veranlaßt das Löschen aller temporären Dateien (zum Beispiel `.o`), die während der Übersetzung erzeugt wurden.

Das genaue Verhalten von `clean` kann von einer Reihe von Variablen beeinflußt werden. Stellvertretend seien hier `CLOBBER` und `RECURSE` genannt.

### 4.2.5.11. Text buchstabengetreu übernehmen

Für das Handbuch ist es oft notwendig, Textausschnitte buchstabengetreu darzustellen. Hierbei kann es sich um Texte handeln, die aus einer anderen Datei stammen oder die der Leser eins-zu-eins aus dem Handbuch kopieren können soll.

In einigen Fällen ist zu diesem Zwecke `<programlisting>` ausreichend, jedoch nicht immer. So ist `<programlisting>` zum Beispiel nicht einsetzbar, wenn es darum geht, einen Auszug aus einer Datei innerhalb eines Absatzes einzufügen. In solchen Fällen sollte das Element `<literal>` zum Einsatz kommen.

Beispiel 4-44. `<literal>`

    <para>Die Zeile <literal>maxusers 10</literal> in der
      Kernelkonfigurationsdatei beeinflußt die Größe vieler
      Systemtabellen und kann als ungefähr als Richtwert dafür
      gelten, wie viele paralle Anmeldungen das System handhaben
      kann.</para>

Darstellung:

Die Zeile `maxusers 10` in der Kernelkonfigurationsdatei beeinflußt die Größe vieler Systemtabellen und kann als ungefähr als Richtwert dafür gelten, wie viele paralle Anmeldungen das System handhaben kann.

### 4.2.5.12. Benutzerspezifische Eingaben darstellen

Es kommt oft vor, dass der Leser Beispiele, Dateinamen oder Kommandozeilen verändern muss. Für einen solchen Anwendungsfall ist das Element `<replaceable>` gedacht. Es kann innerhalb von anderen Elementen genutzt werden, um die Teile auszuzeichnen, die es zu ersetzen gilt.

Beispiel 4-45. Das Element `<replaceable>`

    <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>

Darstellung:

    % man command

Dieses Beispiel zeigt, dass nur der Text mit `<replaceable>` umschlossen werden soll, den der Benutzer einzusetzen hat. Sämtlicher anderer Text sollte wie üblich ausgezeichnet werden.

    <para>Die Zeile
      <literal>maxusers <replaceable>n</replaceable></literal>
      in der Kernelkonfigurationsdatei bestimmt die Größe vieler Systemtabellen
      und stellt einen groben Richtwert dafür dar, wie viele gleichzeitige Anmeldungen
      das System unterstützt.</para>

    <para>Für einen Arbeitsplatzrechner stellt <literal>32</literal> einen guten
      Wert für <replaceable>n</replaceable> dar.</para>

Darstellung:

Die Zeile `maxusers `n`` in der Kernelkonfigurationsdatei bestimmt die Größe vieler Systemtabellen und stellt einen groben Richtwert dafür dar, wie viele gleichzeitige Anmeldungen das System unterstützt.

Für einen Arbeitsplatzrechner stellt `32` einen guten Wert für `n` dar.

### 4.2.5.13. Fehlermeldungen des Systems darstellen

In manchen Fällen kann es nötig sein, Fehlermeldungen darzustellen, die von FreeBSD erzeugt werden können. Für solche Fälle ist das Element `<errorname>` vorgesehen.

Beispiel 4-46. Das Element `<errorname>`

     <screen><errorname>Panic: cannot mount root</errorname></screen>

Darstellung:

    “Panic: cannot mount root”

## 4.2.6. Bilder und Grafiken

> Wichtig: Die Verwendung von Grafiken innerhalb der Dokumentation ist momentan noch in einem experimentellen Stadium. Es ist daher wahrscheinlich, dass sich die hier beschriebenen Mechanismen noch ändern werden.

> Für die Verwendung von Grafiken ist es notwendig, den Port `graphics/ImageMagick` zusätzlich zu installieren, da er nicht vom Port `textproc/docproj` mitinstalliert wird.

> Das beste Beispiel für den Einsatz von Grafiken ist der unter `doc/en_US.ISO8859-1/articles/vm-design/` zu findene Artikel “Design elements of the FreeBSD VM system”. Falls beim Lesen der folgenden Kapitel Fragen unbeantwortet oder unklar bleiben, empfiehlt es sich, die unter dem genannten Verzeichnis befindlichen Dateien zu studieren und anhand ihrer zu verstehen, wie alles zusammenhängt. Es empfiehlt sich, den Artikel in verschiedenen Ausgabeformaten zu erzeugen, da man so sehen kann, wie die Grafiken in Abhängigkeit vom Ausgabemedium angeordnet werden.

### 4.2.6.1. Unterstütze Grafikformate

Zur Zeit werden nur zwei Grafikformate unterstützt. Welches von beiden Formaten zum Einsatz kommen sollte, hängt von der Art der Grafik ab.

Für Bilder, die vorrangig Vektorelemente wie Netzwerkdiagramme, Zeitlinien und ähnliches beinhalten, sollte Encapsulated Postscript als Format gewählt werden. Wichtig ist es in diesem Fall, dass die Grafikdatei die Endung `.eps` hat. Für Bitmapgrafiken, wie zum Beispiel Bildschirmfotos, steht das Portable Network Grafic Format zur Verfügung. In diesem Fall, sollte die Grafikdatei immer die Endung `.png` haben.

In das CVS-Archiv sollten nur Grafiken in diesen beiden Formaten übernommen werden.

Es sollte darauf sehr darauf geachtet werden, das richtige Format für das richtige Bild zu wählen. Erwartungsgemäß wird es Dokumente geben, die eine Mischung aus PNG- und EPS-Grafiken enthalten. In solchen Fällen, stellen die Makedateien die Verwendung des richtigen Formats in Abhängigkeit vom Ausgabeformat sicher. Deshalb sollte die gleiche Grafik niemals in zwei unterschiedlichen Formaten in das CVS-Archiv übernommen werden.

> Wichtig: Es ist absehbar, dass das Dokumentationsprojekt in Zukunft das Scalable Vector Graphic-Format (SVG) als Standardformat für Vektorgrafiken übernehmen wird. Zum jetzigen Zeitpunkt ist dieser Wechsel noch nicht möglich, da der Stand der jetzigen SVG-Anwendungen noch nicht den dafür notwendigen Erfordernissen entspricht.

### 4.2.6.2. DocBook-Elemente für den Grafikeinsatz

Das Auszeichnen von Bildern mittels DocBook ist relativ einfach. Zuerst wird ein `<mediaobject>`-Element eingefügt, das als Container für medienspezifische Elemente fungieren kann. Für die Zwecke des FDPs sind das die Elemente `<imageobject>` und `<textobject>`.

In das `<mediaobject>`-Element sollten ein Element vom Typ `<imageobject>` und zwei `<textobject>`-Elemente eingefügt werden. Das `<imageobject>`-Element verweist auf die eigentliche Grafikdatei. Dabei ist allerdings nur der Dateipfad ohne Erweiterung anzugegeben. Die `<textobject>`-Elemente werden dafür genutzt, Texte aufzunehmen, die dem Leser anstelle des Bildes oder zusammen mit dem Bild angezeigt werden.

Dies kann unter zwei Umständen geschehen:

- Wenn ein Dokument als HTML-Datei durch einem Browser angezeigt wird. In diesem Falle muss jeder Grafik ein Alternativtext zugeordnet werden, der dem Leser angezeigt werden kann. Meist ist das notwendig, wenn der Browser die Grafik noch nicht geladen hat oder wenn der Benutzer den Mauszeiger über die Grafik führt.

- Wenn das Dokument als Textdatei gelesen wird. Da in einer Textdatei keine Grafiken angezeigt werden können, sollte es für die Grafik eine Textentsprechung geben, die alternativ angezeigt werden kann.

Das folgende Beispiel soll das bisher geschriebene illustrieren. Angenommen es liegt eine einzubindene Grafik in der Datei `bild1` vor, die die Darstellung eines As in einem Rechteck enthält. Die ASCII-Alternative könnte so ausgezeichnet werden:

    <mediaobject>
      <imageobject>
        <imagedata fileref="bild1">
      </imageobject>
      <textobject>
        <literallayout class="monospaced">+ - - - - - - - - - - - - - - -+
    |       A       |
    +- - - - - - - - - - - - - - -+</literallayout>
      </textobject>
      <textobject>
        <phrase>Ein Bild</phrase>
      </textobject>
    </mediaobject>

  Innerhalb vom Element `<imageobject>` befindet sich ein Element `<imagedata>`, welches mit Hilfe des Attributes `fileref` den Namen der Grafikdatei (ohne Erweiterung) angibt. Die Bestimmung der Dateierweiterung wird von den Stylesheets übernommen.
  Das erste `<textobject>`-Element enthält ein `<literallayout>`-Element, dessen Attribut `class` den Wert `monospaced` zugewiesen bekommt. Der Inhalt dieses Elements wird genutzt, wenn das Dokument in Textform ausgegeben wird. An dieser Stelle hat der Autor die Möglichkeit seine “Textzeichenkünste” unter Beweis zu stellen.

  Wichtig ist, dass die erste und die letzte Zeile sich gleichauf mit dem öffenden und dem schließenden Tag befindet. Dadurch wird sichergestellt, dass keine unnötigen Leerzeichen in die Ausgabe aufgenommen werden.

  Das zweite `<textobject>`-Element sollte lediglich ein `<phrase>`-Element enthalten. Wird das Dokument nach HTML konvertiert, wird dessen Inhalt für das Attribut `alt` des `<img>`-Tags verwendet.

### 4.2.6.3. Die `Makefile`-Einträge

Alle in einem Dokument verwendeten Grafiken müssen in dem zugehörigen Makefile in der Variable `IMAGES` enthalten sein. `IMAGES` sollte immer die Namen der Quellgrafiken enthalten. Werden in einem Dokument beispielsweise die drei Grafiken `bild1.eps`, `bild2.png` und `bild3.png` referenziert, sollte das `Makefile` die folgende Zeile enthalten:

    ...
    IMAGES= bild1.eps bild2.png bild3.png
    ...

Eine andere Möglichkeit wäre:

    ...
    IMAGES=  bild1.eps
    IMAGES+= bild2.png
    IMAGES+= bild3.png
    ...

Es kann nicht oft genug betont werden: Welche Grafikdateien für das zu erzeugende Dokument benötigt werden, wird von dem Makefiles bestimmt. `IMAGES` darf nur die Originaldateien enthalten.

### 4.2.6.4. Grafiken und Kapitel in Unterverzeichnissen

Wenn Sie Ihre Dokumentation in mehrere kleine Dateien aufspalten (siehe Abschnitt 3.7.1), müssen Sie sorgfältig vorgehen.

Angenommen es handelt sich um ein Buch, dessen drei Kapitel in separaten Verzeichnissen angelegt wurden (`kapitel1/kapitel.sgml`, `kapitel2/kapitel.sgml` und `kapitel3/kapitel.sgml`). Enthalten die Kapitel Grafiken, empfiehlt es sich, diese in den gleichen Verzeichnisses abzulegen, wie die Kapitel selbst. In diesem Falle gilt es jedoch zu beachten, dass die Pfade der Grafikdateien in der Variable `IMAGES` und in den `<imagedata>`-Elementen immer auch den Verzeichnisnamen mitenthalten.

Soll beispielsweise die Datei `kapitel1/bild1.png` in das in `kapitel1/kapitel.sgml` enthaltene Kapitel eingebunden werden, sollte dies so erfolgen:

    <mediaobject>
      <imageobject>
        <imagedata fileref="kapitel1/bild1">
      </imageobject>

      ...
    </mediaobject>

  `fileref` muss den Datei- und den Verzeichnisnamen enthalten.

Das `Makefile` muss dementsprechend die Zeile

    ...
    IMAGES=  kapitel1/bild1.png
    ...

enthalten.

Wird dies beachtet, sollte es zu keinen Problemen kommen.

## 4.2.7. Querverweise

> Anmerkung: Querverweise sind auch Flußelemente.

### 4.2.7.1. Querverweise innerhalb eines Dokumentes

Um innerhalb eines Dokumentes Verweise anzulegen, muss angegeben werden, von welcher Textstelle aus wohin verwiesen werden soll.

Jedes DocBook-Element besitzt ein Attribut `id`, über das seinem Element ein eindeutiger Bezeichner zugewiesen werden kann.

In den meisten Fällen werden Querverweise nur zu Kapiteln gesetzt. Die `<chaper>`- und `<sect*>`-Elemente sollten aus diesem Grunde ein gesetztes `id`-Attribut besitzen.

Beispiel 4-47. `<chapter>` und `<section>` mit dem Attribut `id`

    <chapter id="kapitel1">
      <title>Einführung</title>

      <para>Das ist eine Einführung. Sie enthält ein Unterkapitel, das
        ebenfalls einen eigenen Bezeichner hat.</para>

      <sect1 id="kapitel1-unterkapitel1">
        <title>Unterkapitel 1</title>

        <para>Das ist ein Unterkapitel.</para>
      </sect1>
    </chapter>

Als Wert für das Attribut `id` sollte immer ein selbsterklärender Bezeichner gewählt werden. Zudem ist es notwendig, dass dieser Bezeichner innerhalb des Dokumentes eindeutig ist. Im obigen Beispiel wurde der Bezeichner für das Unterkapitel gebildet, indem der Bezeichner des übergeordneten Kapitels um den Titel des Unterkapitels erweitert wurde. Diese Vorgehensweise hilft sicherzustellen, dass Bezeichner eindeutig sind und bleiben.

Manchmal soll jedoch nicht auf den Anfang eines Kapitels verwiesen werden, sondern zum Beispiel auf eine Stelle in einem Absatz oder auf ein bestimmtes Beispiel. In solchen Fällen kann an der Stelle, auf die verwiesen werden soll, das Element `<anchor>` mit gesetztem Attribut `id` eingefügt werden. `<anchor>` kann selber keinen weiteren Inhalt aufnehmen.

Beispiel 4-48. Querverweise und das Element `<anchor>`

    <para>Dieser Absatz enthält ein
      <anchor id="absatz1">Ziel für Querverweise, was jedoch keine
      Auswirkung auf dessen Darstellung hat.</para>

Zum Anlegen des eigentlichen Querverweises selbst kann eines der beiden Elemente `<xref>` oder `<link>` genutzt werden. Beide besitzen das Attribut `linkend`, dem der `id`-Wert des Verweiszieles zugewiesen wird. Ob sich das Ziel vor oder nach dem Verweis befindet, spielt keine Rolle.

`<xref>` und `<link>` unterscheiden sich jedoch hinsichtlich der Art und Weise, auf die der Text erzeugt wird, auf dem der Querverweis liegt. Kommt `<xref>` zum Einsatz, hat der Autor keine Kontrolle darüber - der Text wird automatisch für ihn erzeugt.

Beispiel 4-49. Einsatz von `<xref>`

Für dieses Beispiel wird davon ausgegangen, dass sich folgendes Textfragment irgendwo innerhalb eines Dokumentes auftaucht, dass das vorherige `id`-Beispiel enthält.

    <para>Weitere Informationen gibt
      es im <xref linkend="kapitel1">.</para>

    <para>Genauere Informationen können im
      <xref linkend="kapitel1-unterkapitel1"> gefunden werden.</para>

Der Verweistext wird automatisch von den Stylesheets erzeugt und so hervorgehoben, dass ersichtlich ist, dass es sich bei dem Text um einen Verweis handelt.

> Weitere Informationen können in der Einführung gefunden werden.

> Genauere Informationen können im Unterkapitel 1 gefunden werden.

Der Text, auf dem der HTML-Link für den Querverweis liegt, wurde von den Kapitelüberschriften übernommen.

> Anmerkung: Das bedeutet, dass es nicht möglich ist, mit der Hilfe von `<xref>` einen Querverweis zu einer mit `<anchor>` gekennzeichneten Stelle anzulegen. Da `<anchor>` keinen Inhalt aufnehmen kann, können die Stylesheets nicht automatisch einen Text für den Verweis erzeugen.

Möchte man selber den für den Verweis benutzten Text bestimmen können, sollte das Element `<link>` verwendet werden. Im Gegensatz zu `<xref>` kann `<link>` Inhalt aufnehmen, der dann für den Verweis verwendet wird.

Beispiel 4-50. `<link>` beutzen

Für dieses Beispiel wird davon ausgegangen, dass es sich in dem Dokument befindet, das auch das `id`-Beispiel enthält.

    <para>Weitere Informationen können
      im <link linkend="kapitel1">ersten Kapitel</link> gefunden
      werden.</para>

    <para>Genauere Informationen können in
      <link linkend="kapitel1-unterkapitel1">diesem</link> Kapitel
      gefunden werden.</para>

Aus diesem SGML-Fragment würden die Stylesheets folgendes generieren (der hervorgehobene Text deutet den erzeugten Verweis an):

> Weitere Informationen können im ersten Kapitel gefunden werden.

> Genauere Informationen können in diesem Kapitel gefunden werden.

> Anmerkung: Das letzte Beispiel ist schlecht. Es sollten niemals Wörter wie “dieses” oder “hier” als Linktext benutzt werden. Solche Wörter zwingen den Leser dazu, den Kontext des Verweises zu lesen, um zu verstehen, wohin der Verweis führt.

> Anmerkung: Mit dem Element `<link>` kann auf mit `<anchor>` gekennzeichnete Stellen im Dokument verwiesen werden, da der Inhalt von `<link>` als Text für den Querverweise genutzt wird.

### 4.2.7.2. Verweise auf Dokumente im WWW

Das Anlegen von Verweisen auf externe Dokumente ist wesentlich einfacher - solange die URL des zu referenzierenden Dokumentes bekannt ist. Um von einem bestimmten Textabschnitt auf das gewünschte externe Dokument zu verweisen, muss die jeweilige Stelle mit dem Element `<ulink>` ausgezeichnet werden. Mittels des Attributes `url` kann die Adresse des Zieldokumentes angegeben werden. Bei der Umformung des Quelldokumentes in die verschiedenen Ausgabeformate wird der sich zwischen Start- und Endtag befindliche Text für den Verweis übernommen, den der Leser aufrufen kann.

Beispiel 4-51. Verweise mit `<ulink>`

    <para>Natürlich ist es möglich, anstatt diesen Text
      weiterzulesen, sofort die
      <ulink url="../../../../de/index.html">FreeBSD-Homepage</ulink>
      aufzurufen.<para>

Darstellung:

Natürlich ist es möglich, anstatt diesen Text weiterzulesen, sofort die FreeBSD-Homepage aufzurufen.

### Fußnoten

[1] | Einen kurzen historischen Abriss finden Sie unter http://www.oasis-open.org/docbook/intro.shtml#d0e41.
[2] | DocBook kennt noch andere Elemente für die Auszeichnung von Listen, die an dieser Stelle jedoch nicht behandelt werden.
[3] | auf Englisch: callout
[4] | Anmerkung des Übersetzers: Hier sollte man sich noch einmal ins Gedächtnis rufen, dass mittels der DocBook DTD nur Inhalte ausgezeichnet werden und nicht das Layout bestimmt wird.
[5] | Der Befehl `mozilla` startet das Programm mozilla.

Zurück | Zum Anfang | Weiter
SGML-Dokumente erstellen | Nach oben | Stylesheets

Wenn Sie Fragen zu FreeBSD haben, schicken Sie eine E-Mail an <de-bsd-questions@de.FreeBSD.org>.
Wenn Sie Fragen zu dieser Dokumentation haben, schicken Sie eine E-Mail an <de-bsd-translators@de.FreeBSD.org>.