3.3.1.1. Die catalog-Dateien

Wenn man die oben beschriebene Syntax für Bezeichner verwendet und ein Dokument durch einen SGML-Prozessor schickt, muss dieser die Möglichkeit haben, den Bezeichner auf eine real existierende Datei abzubilden, die die benötigte DTD enthält.

Einer der möglichen Wege hierfür sind Katalogdateien. Eine solche Datei, die üblicherweise catalog heißt, besteht aus einzelnen Zeilen, die Bezeichner auf Dateinamen abbilden. Enthält ein Katalog beispielsweise die Zeile

PUBLIC "-//W3C//DTD HTML 4.0//EN"             "4.0/strict.dtd"

kann ein SGML-Prozessor darüber feststellen, dass die benötigte DTD in der Datei strict.dtd im Unterverzeichnis 4.0 des Verzeichnisses des Katalogs zu finden ist.

Ein gutes Beispiel für einen Katalog ist /usr/local/share/xml/html/catalog. Diese Datei enthält den Katalog für alle HTML DTDs, die im Zuge der Installation von textproc/docproj installiert wurden.

3.3.1.2. Die Variable SGML_CATALOG_FILES

Natürlich muss einem SGML-Prozessor noch mitgeteilt werden können, wo er seine Kataloge finden kann. Viele Programme bieten hierfür Kommandozeilenoptionen an, über die man einen oder mehrere Kataloge angeben kann.

Zusätzlich besteht noch die Möglichkeit mit der Umgebungsvariablen SGML_CATALOG_FILES auf SGML-Kataloge zu verweisen. Die Einträge von SGML_CATALOG_FILES müssen aus den vollständigen Pfadnamen der Kataloge, jeweils durch Komma getrennt, bestehen.

Üblicherweise werden die folgenden Kataloge über SGML_CATALOG_FILES für die Arbeit an den Dokumenten des FDPs eingebunden:

• /usr/local/share/xml/docbook/4.1/catalog

• /usr/local/share/xml/html/catalog

• /usr/local/share/xml/iso8879/catalog

• /usr/local/share/xml/jade/catalog

Allerdings sollte das schon geschehen sein.

3.7.3.1. Binden Sie Dateien über Allgemeine Entitäten ein

3.7.3.2. Binden Sie Dateien mit Parameterentitäten ein

3.8.1.1. CDATA und RCDATA

Die Schlüsselworte CDATA und RCDATA bestimmen das Inhaltsmodell für markierte Bereiche. Dadurch ist es möglich, vom Standardmodell abzuweichen.

Ein SGML-Prozessor muss während der Verarbeitung eines Dokuments zu jedem Zeitpunkt wissen, welches Inhaltsmodell gerade anzuwenden ist.

Was ist ein Inhaltsmodell? Kurz gesagt beschreibt das Inhaltsmodell, welche Art von Inhalt der Parser zu erwarten und wie er damit umzugehen hat.

Bei CDATA und RCDATA handelt es sich wahrscheinlich um die nützlichsten Inhaltsmodelle. CDATA steht für Zeichendaten[9]. Trifft ein Parser auf dieses Inhaltsmodell, wird er annehmen, dass sich im zugehörigen Dokumentenbereich nur “gewöhnliche” Zeichen befinden. Das bedeutet, dass < und & ihre besondere Bedeutung verlieren und als einfache Zeichen behandelt werden.

RCDATA steht für Entitätenreferenzen und Zeichendaten[10]. Für einen Bereich mit diesem Inhaltsmodell, wird ein Parser davon ausgehen, dass er sowohl Zeichen als auch Enitätenreferenzen finden kann. < verliert hier zwar auch seine besondere Bedeutung, doch & wird weiterhin als Anfang einer Entität interpretiert.

Nützlich ist das CDATA-Modell vor allem dann, wenn es darum geht Texte eins-zu-eins zu übernehmen, in denen < und & gehäuft auftreten. Zwar kann man solche Texte überarbeiten und jedes < durch ein &lt; und jedes & durch ein &amp; ersetzen, doch es wird in den meisten Fällen einfacher sein, für den betreffenden Text CDATA als Inhaltsmodell festzulegen. Ein SGML-Parser wird dann, sobald er auf < oder & trifft, diese als Zeichen in einem Text betrachten.

<para>Das ist ein Beispiel, wie man einen Text,
  der viele &lt;- und &amp;-
  Entitäten enthält, in ein Dokument einbinden kann.
  Das Beispiel selbst, das sich innerhalb des markierten Bereiches befindet,
  ist ein HTML-Fragment. Der diesen Text umschließende Tag, beginnend mit
  mit <para> und endend mit </para>, stammt aus der DocBook DTD.</para>

<programlisting>
  <![RCDATA[  
    <p>Dieses Beispiel demonstriert die Verwendung von HTML-Elementen.
      Da spitze Klammern so oft vorkommen, ist es einfacher, das
      gesamte Beispiel als CDATA Abschnitt auszuweisen, als die
      entsprechenden Entitäten zu nutzen.</p>

    <ul>
      <li>Das ist ein Listenelement.</li>
      <li>Das ist ein zweites Listenelement.</li>
      <li>Das ist ein drittes Listenelement.</li>
    </ul>

    <p>Und das hier, das ist das Ende des Beispiels.</p>
  ]]>
</programlisting>

3.8.1.2. INCLUDE und IGNORE

Das Schlüsselwort INCLUDE legt fest, dass der Inhalt des betreffenden Abschnittes mitverarbeitet wird. Demgegenüber bestimmt IGNORE, dass er ignoriert wird, dass heißt, dass er bei der Verarbeitung übergangen wird und in der Ausgabe nicht enthalten ist.

<![ INCLUDE [
  Dieser Text wird verarbeitet und eingebunden.
]]>

<![ IGNORE [
  Dieser Text wird weder verarbeitet noch eingebunden.
]]>

Für sich alleine ist IGNORE als Anweisung nicht besonders nützlich, da ein Bereich, der von der Verarbeitung ausgenommen sein soll, auch auskommentiert werden kann.

Kombiniert man IGNORE hingegen mit Parameterentitäten, steht so ein Weg zur Verfügung, um dessen Anwendung besser steuern zu können. Zwar können Parameterentitäten nur in einem SGML-Kontext einsetzt werden, da aber markierte Bereiche ebenfalls SGML-Konstrukte sind, ist diese Einschränkung irrelevant.

Soll beispielsweise ein und dasselbe Dokument in zwei unterschiedlichen Varianten produziert werden, einer gedruckten und einer digitalen, und soll nur die digitale zusätzliche Informationen enthalten, kann dies mit einem Trick erreicht werden.

Man definiert eine Parameterentität, der man als Wert die Zeichenkette INCLUDE zuweist und deklariert den betreffenden Bereich, der nur in der digitalen Variante erscheinen soll, als markierten Abschnitt und setzt als Schlüsselwort die zuvor definierte Parameterentität ein.

Soll anstelle der digitalen die gedruckte Variante produziert werden, muss lediglich der Entität IGNORE als Wert zugewiesen und das Ursprungsdokument erneut durch den SGML-Prozessor geschickt werden.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % digitale.kopie "INCLUDE">
]]>

...

<![ %digitale.kopie [
  Dieser Satz sollte nur in der digitalen Version enthalten sein.
]]>	 

<!ENTITY % digitale.kopie "IGNORE">

4.1.3.1. Überschriften

HTML kennt sechs verschiedene Elemente, mit denen Überschriften ausgezeichnet werden können. Das bekannteste Element ist <h1>, das sich am Anfang der Überschriftenhierarchie befindet. <h1> folgen die Überschriftenelemente <h2> bis <h6>. Der Inhalt von <hN> stellt den Text der Überschrift dar.

<h1>Erstes Kapitel</h1>

<!-- Hier steht die Einführung -->

<h2>Das ist die Überschrift des ersten Kapitels</h2>

<!-- Hier steht der Inhalt des ersten Kapitels -->

<h3>Das ist die Überschrift des ersten Unterkapitels</h3>

<!-- Hier steht der Inhalt des ersten Unterkapitels -->

<h2>Das ist die Überschrift des zweiten Kapitels</h2>

<!-- Hier steht der Inhalt des zweiten Kapitels -->

Eine HTML-Seite sollte immer nur eine Überschrift <h1> haben. Dieser Überschrift können beliebig viele Kapitel mit einer Überschrift <h2> folgen, die selbst wiederum eine beliebige Anzahl von Kapiteln mit einer Überschrift <h3> enthalten können. Diese Verschachtelung setzt sich bis zu Kapiteln mit einer <h6>-Überschrift fort. Es sollte vermieden werden, Elemente in der Überschriftenhierarchie auszulassen.

<h1>Erstes Kapitel</h1>

<!-- Allgemeines zum Dokument -->

<h3>Unterkapitel</h3>

<!-- h3 folgt direkt auf h1. h2 wurde ausgelassen -->

4.1.3.2. Absätze

Absätze können in HTML mit Hilfe des Elementes <p> ausgezeichnet werden.

<p>Das hier, das ist ein Absatz. Absätze können
  andere Elemente enhalten.</p>

4.1.3.3. Blockzitate

Ein Blockzitat ist ein etwas umfangreicheres Zitat aus einem anderen Text, das nicht zum aktuellen Absatz gehört.

<blockquote>
  <p>Artikel 1: Menschenwürde; Grundrechtsbindung der
    staatlichen Gewalt</p>

  <ol>
    <li>
      <p>Die Würde des Menschen ist unantastbar. Sie zu achten
        und zu schützen ist Verpflichtung aller staatlichen
        Gewalten.</p>
    </li>
    <li>
      <p>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.</p>
    </li>
    <li>
      <p>Die nachfolgenden Grundrechte binden Gesetzgebung,
        vollziehende Gewalt und Rechtsprechung als
        unmittelbar geltendes Recht.</p>
    </li>
  </ol>
</blockquote>

4.1.3.4. Listen

HTML kennt drei Arten von Listen: sortierte, unsortierte und Definitionslisten. Ein Eintrag in einer sortierten Liste wird üblicherweise mit einer Nummer versehen, Einträge in unsortierten Listen hingegen mit einem Aufzählungspunkt. Definitionslisten wiederum bestehen aus zwei Teilen: Der erste enthält den Begriff der definiert werden soll und der zweite dessen Erläuterung.

Sortierte Listen werden mit dem Element <ol> (für ordered list) ausgezeichnet, unsortierte Listen mit <ul> (für unordered list) und Definitionslisten mit <dl>.

Listenpunkte sortierter und unsortierter Listen werden mit dem Element <li> ausgezeichnet, welches Text oder andere Blockelemente enthalten kann. Begriffe, die in einer Definitionslisten enthalten sind, werden mit dem Element <dt> (für definition term) ausgezeichnet. Die Erklärung zu diesem Begriff wird mit Hilfe des Elementes <dd> (für definition description) markiert. So wie <li>, kann das Element <dd> ebenfalls andere Blockelemente aufnehmen.

<p>Jetzt folgt eine unsortierte Liste. Wahrscheinlich werden
  die einzelnen Einträge mit einem vorangehenden Punkt dargestellt.</p>

<ul>
  <li>Erster Eintrag</li>

  <li>Zweiter Eintrag</li>

  <li>Dritter Eintrag</li>
</ul>

<p>Die zweite Liste ist sortiert und ihre Einträge bestehen aus mehreren Absätzen.
  Jeder Listeneintrag ist nummeriert.</p>

<ol>
  <li><p>Das ist der erste Eintrag mit nur einem Absatz.</p></li>

  <li><p>Das ist der erste Absatz des zweiten Eintrags.</p>

    <p>Und das ist der zweite Absatz des zweiten Eintrags.</p></li>

  <li><p>Der dritte Eintrag besteht ebenfalls nur aus einem Eintrag.</p></li>
</ol>

<dl>
  <dt>Erster Begriff</dt>

  <dd><p>Erster Absatz der Erklärung</p>

    <p>Zweiter Absatz der Erklärung.</p></dd>

  <dt>Zweiter Begriff</dt>

  <dd><p>Erster Absatz der Erklärung.</p></dd>

  <dt>Dritter Begriff</dt>

  <dd>Erster Absatz der Erklärung zum dritten Begriff.</dd>
</dl>

4.1.3.5. Vorformatierter Text

In einigen Fällen ist es gewollt, dass die Formatierung eines Textes im Quelldokument erhalten bleibt, damit der Leser diesen genau so sieht, wie ihn der Autor erstellt hat. In der HTML-Spezifikation ist dafür das Element <pre> vorgesehen, welches dafür sorgt, dass Zeilenumbrüche erhalten bleiben und Leerzeichen nicht zusammengefaßt werden. Browser verwenden für den Inhalt des Elementes <pre> üblicherweise eine Fixschrift.

<pre>  From: nik@FreeBSD.org
  To: freebsd-doc@FreeBSD.org
  Subject: Neue Version verfügbar

  Es ist eine neue Version der Fibel für neue Mitarbeiter am
  FreeBSD-Dokumentationsprojekt verfügbar:

    &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;

  Kommentare und Anmerkungen sind willkommen.

  N</pre>

4.1.3.6. Tabellen

Tabellen lassen sich in HTML mit Hilfe des Elements <table> auszeichnen. Eine Tabelle setzt sich aus einer oder mehreren Zeilen (<tr>) zusammen, von denen jede mindestens eine Zelle (<td>) enthält. Zellen können wiederum andere Blockelemente, wie Absätze oder Listen, enthalten. Auch können sie auch andere Tabellen aufnehmen, wobei die Verschachtelungstiefe unbegrenzt ist. Soll die Tabellenzelle nur einen Textabsatz enthalten, ist es nicht notwendig den Text mit einem <p> zu umschließen.

<p>Eine einfache 2x2 Tabelle.</p>

<table>
  <tr>
    <td>Obere linke Zelle</td>

    <td>Obere rechte Zelle</td>
  </tr>

  <tr>
    <td>Untere linke Zelle</td>

    <td>Untere rechte Zelle</td>
  </tr>
</table>

HTML kennt die Möglichkeit, dass sich eine Zelle mehrere Zeilen und/oder Spalten erstrecken kann. Sollen beispielsweise mehrere Spalten zusammenfassen werden, kann dies mit mit Hilfe des Attributes colspan erreicht werden, indem man ihm die Anzahl der zusammenzufassenden Spalten zuweist. Ähnliches gilt für die Zusammenfassung von Zeilen: Hierfür wird dem Attribut rowspan die Anzahl der zusammenzufassenden Zeilen zugewiesen.

<p>Diese Tabelle besteht aus einer langen Zelle auf der
  linken Seite und zwei kleineren Zellen auf der rechten.</p>

<table>
  <tr>
    <td rowspan="2">Lang und dünn</td>
  </tr>

  <tr>
    <td>Obere Zelle</td>

    <td>Untere Zelle</td>
  </tr>
</table>

<p>Eine breite Zeile oben und zwei schmalere Zeilen
  darunter.</p>

<table>
  <tr>
    <td colspan="2">Obere Zelle</td>
  </tr>
  <tr>
    <td>Linke untere Zelle</td>

    <td>Rechte untere Zelle</td>
  </tr>
</table>

<p>Eine Tablle mit 3-mal-3 Zellen. Oben links
  werden 2 mal 2 Zelle zusammengezogen.</p>

<table>
  <tr>
    <td colspan="2" rowspan="2">Große obere linke Zelle</td>

    <td>Obere rechte Zelle</td>
  </tr>

  <tr>
    <!-- Da sich die zusammengefaßte Zelle über zwei Zeilen
         erstreckt, befindet sich das die durch dieses <td>
         definierte Zelle ganz rechts. -->

    <td>Mittlere rechte Zelle</td>
  </tr>

  <tr>
    <td>Untere linke Zelle</td>

    <td>Untere mittlere Zelle</td>

    <td>Untere rechte Zelle</td>
  </tr>
</table>

4.1.4.1. Hervorheben von Information

Sollen sich bestimmte Informationen von anderen optisch abheben, kann dies mit den HTML-Tags <strong> und <em> erreicht werden. <strong> stellt dabei eine stärkere Hervorhebung als <em> dar, wobei mit <strong> ausgezeichnete Elemente fett und mit <em> ausgezeichnete Elemente kursiv dargestellt werden. Allerdings ist diese Aussage nicht verläßlich, da die Darstellung vom Browser abhängig ist.

<p><em>Dieses</em> Wort ist hervorgehoben,
  während <strong>dieses noch stärker hervorgehoben ist.</p>

4.1.4.2. Fett- und Schrägschrift

Da mittels HTML auch Festlegungen über die Darstellung getroffen werden können, gibt es die Möglichkeit direkt zu bestimmen, dass bestimmte Inhalte fett oder kursiv dargestellt werden sollen. Mit <b> eingefaßte Inhalte werden fett und mit <i> eingefaßte kursiv dargestellt.

<p><b>Dieses</b> Wort wird fett dargestellt,
während <i>dieses</i> kursiv dargestellt wird.</p>

4.1.4.3. Nicht-proportionale Schrift für Texte

Der Tag <tt> erlaubt es, Text in einer schreibmaschinenähnlichen Schrift darzustellen.

<p>Dieses Dokument wurde ursprünglich von
  Nik Clayton geschrieben. Nick Clayton kann unter der E-Mail-Adresse
  <tt>nik@FreeBSD.org</tt> erreicht werden.</p>

4.1.4.4. Änderung der Schriftgröße

HTML bietet auch Möglichkeiten, um Einfluß auf die Schriftgröße zu nehmen, das heißt, zu bestimmen, ob die Schrift größer oder kleiner als die Standardschrift dargestellt werden soll. Es gibt drei verschiedene Wege, dies zu erreichen:

1. Mittels der Tags <big> und <small> kann die Darstellungsgröße des eingeschlossenen Textes vergrößert respektive verkleinert werden. HTML erlaubt es zudem, diese Tags zu verschachteln, so dass auch <big><big>Das ist wesentlich größer.</big></big> geschrieben werden kann.

2. Das gleiche Ergebnis kann über die Zuweisung der Werte 1 und -1 an das Attribut <size> des Tags <font> erreicht werden. Diese Vorgehensweise sollte allerdings als veraltet betrachtet werden, da der Einsatz eines CSS hierfür die bessere Lösung darstellt.

3. Über die Zuweisung von absoluten Werten im Bereich von 1 bis 7 an das Attribut size des Tags <font> [12]. Diese Herangehensweise ist ebenfalls veraltet und sollte nicht mehr angewandt werden.

<p>Dieser Text ist <small>etwas kleiner</small>. Dieser
  jedoch <big>ein wenig größer</big>.</p>

<p>Dieser Text ist <font size="-1">etwas kleiner</font>. Dieser
  jedoch <font size="+1">ein wenig größer</font>.</p>

<p>Dieser Text ist <font size="2">etwas kleiner</font>. Dieser
  jedoch <font size="4">ein wenig größer</font>.</p>

4.1.5.1. Auf andere Dokumente im WWW verweisen

Um auf ein anderes Dokument im WWW zu verweisen, müssen Sie die URL dieses Dokuments kennen.

Links auf andere Dokumente im WWW werden in HTML durch den Tag <a> und dessen Attribute <href>, das die Zieladresse enthält, angelegt. Der Inhalt des Elementes wird selbst zum Link und seine Darstellung erfolgt verschieden vom übrigen Text. Meist geschieht das durch eine andere Schriftfarbe oder dadurch, dass der Linktext unterstrichen wird.

<p>Weitere Informationen stehen auf der
  <a href="http://www.FreeBSD.org/">FreeBSD-Webseite</a> zur Verfügung.</p>

Beim Aufruf dieses Links wird das referenzierte Dokument vom Browser geladen und mit dessen Seitenanfang dargestellt.

4.1.5.2. Auf bestimmte Dokumentenabschnitte verweisen

HTML unterstützt neben einfachen Links auch solche, die auf einen bestimmten Abschnitt innerhalb eines Dokumentes verweisen. Dazu müssen die Abschnitte, auf die verwiesen werden soll, mit Hilfe von sogenannten “Ankern” markiert werden. Diese Anker können ebenfalls mit Hilfe des Tags <a> gesetzt werden, nur das anstelle von <href> das Attribut <name> gesetzt werden muss.

<p><a name="absatz1">Auf</a> diesen Absatz kann mit
  Hilfe seines Namens (<tt>absatz1</tt>) verwiesen werden.</p>

Um auf einen so gekennzeichneten Abschnitt zu verweisen, muss die URL des Dokumentes um das Zeichen # und den Namen des Zielankers erweitert werden.

<p>Weitere Informationen können im
  <a href="foo.html#absatz1">ersten Absatz</a> der Datei
  <tt>foo.html</tt> gefunden werden.</p>

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.

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

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

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

  &hellip;
</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.

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

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

  <para>Ein beliebiger Text.</para>

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

    &hellip;
  </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>

         &hellip;
      </sect3>
    </sect2>

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

      &hellip;
    </sect2>
  </sect1>
</chapter>

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>

     &hellip;
  </chapter>

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

    &hellip;
  </chapter>

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

    &hellip;
  </chapter>
</part>

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.

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

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.

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

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

  <attribution>Aus dem Grundgesetz</attribution>

  <orderedlist>
    <listitem>
      <para>Die Würde des Menschen ist unantastbar. Sie zu achten
        und zu schützen ist Verpflichtung aller staatlichen
        Gewalten.</para>
    </listitem>
    <listitem>
      <para>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.</para>
    </listitem>
    <listitem>
      <para>Die nachfolgenden Grundrechte binden Gesetzgebung,
        vollziehende Gewalt und Rechtsprechung als
        unmittelbar geltendes Recht.</para>
    </listitem>
  </orderedlist>
</blockquote>

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.

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

Eine Warnung wird wie folgt dargestellt:

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.[14].

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

<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&hellip;</para>
  </step>
</procedure>

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.

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

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

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

#include <stdio.h>

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

4.2.4.6. Textanmerkungen

Textanmerkungen[15] 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.

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

<programlisting>#include &amp;lt;stdio.h&amp;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>

#include <stdio.h> 

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

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.

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

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

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>&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>

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

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[16]. Handelt es sich bei dem darzustellenden um eine wichtige Information, kann alternativ <important> verwendet werden.

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

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.

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

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.

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

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[17].

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/xml/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.

<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>, &amp;man.mailq.1;, und &amp;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>

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.

<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.xml</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>

4.2.5.6. Portnamen

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.

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

4.2.5.7. Gerätedateien unterhalb von /dev

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.

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

4.2.5.8. Rechner, Domains, IP-Adressen und mehr

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.

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

4.2.5.9. Benutzernamen

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

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

4.2.5.10. Beschreibung von Makefiles

Zur Beschreibung von Teilen einer Makedatei stehen die beiden Elemente <marketarget> und <makevar> zur Verfügung. <maketarget> bezeichnet ein Ziel eines Makefiles, 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.

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

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.

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

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.

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

% man command

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

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.

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

“Panic: cannot mount root”

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 Subversion-Repository 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.

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>

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.xml, kapitel2/kapitel.xml und kapitel3/kapitel.xml). 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.xml enthaltene Kapitel eingebunden werden, sollte dies so erfolgen:

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

  …
</mediaobject>

Das Makefile muss dementsprechend die Zeile

…
IMAGES=  kapitel1/bild1.png
…

Wird dies beachtet, sollte es zu keinen Problemen kommen.

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.

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

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

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

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

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

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.

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

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.

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

6.3.1.1. Physikalische Organisation

Das Verzeichnis handbook enthält sowohl weitere Verzeichnisse als auch zahlreiche einzelne Dateien.

<chapter id="kernelconfig">
...
</chapter>

7.3.1.1. Variablen

DOCFORMAT und MAINTAINER enthalten Standardwerte, falls ihnen über das Dokument-Makefile keine anderen Werte zugewiesen werden.

Bei PREFIX handelt es sich um das Präfix, unter dem die zum Bau der Dokumentation erforderlichen SGML-Werkzeuge installiert sind. In der Regel handelt es sich dabei um /usr/local.

PRI_LANG sollte auf die Sprache und Kodierung eingestellt werden, die unter den Leser der Dokumentation am häufigsten verwendet wird. Diese Variable hat den Standardwert "US English".

7.3.1.2. Bedingungen

Die Zeile .if defined(DOC) ist ein Beispiel für eine make-Bedingung, die (analog zum Einsatz in anderen Programmen) festlegt, was geschehen soll, wenn eine Bedingung "wahr" oder "falsch" ist. defined ist eine Funktion, die zurückgibt, ob die angegebene Variable existiert oder nicht.

.if ${DOCFORMAT} == "docbook" testet, ob die Variable DOCFORMAT den Wert "docbook" hat. Ist dies der Fall, wird doc.docbook.mk mit in den Bau aufgenommen.

Die zwei .endifs schließen die zwei weiter oben definierten Bedingungen.

7.3.2.1. Variablen

• SUBDIR legt die Unterverzeichnisse fest, deren Inhalt beim Bau der Dokumentation inkludiert werden muss.

• Mit ROOT_SYMLINKS wird der Name der Verzeichnisse angegeben, die von ihrer tatsächlichen Position aus in das Wurzelverzeichnis, unter dem die Dokumentation installiert wird, verlinkt werden sollen. Vorausgesetzt, bei der verwendeten Sprache handelt es sich um die primäre Sprache (die über PRI_LANG festgelegt wird).

• COMPAT_SYMLINK wird im Abschnitt Unterverzeichnis-Makefiles beschrieben.

7.3.2.2. Targets und Makros

Abhängigkeiten (Dependencies) werden folgendermaßen definiert: target abhaengigkeit1 abhaengigkeit2 .... Um target zu bauen, müssen Sie zuvor die angegebenen Abhängigkeiten bauen.

Daran anschließend können Anweisungen zum Bau des angegebenen Targets folgen, falls der Konvertierungsprozess zwischen dem Target und seinen Abhängigkeiten nicht bereits früher definiert wurde oder falls die Konvertierung nicht der Standardkonvertierungsmethode entspricht.

Die spezielle Abhängigkeit .USE definiert das Äquivalent eines Makros.

_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===> ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} && \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor

In diesem Beispiel kann _SUBDIRUSE nun als Makro, welches die angegebenen Befehle ausführt, verwendet werden, indem es im Makefile als Abhängigkeit angegeben wird.

Was unterscheidet dieses Makro nun von beliebigen anderen Targets? Der Hauptunterschied ist, dass es nach den Anweisungen der Bauprozedur, in der es als Abhängigkeit angegeben ist, ausgeführt wird. Außerdem ändert es die Variable .TARGET (die den Namen des aktuell gebauten Targets enthält) nicht.

clean: _SUBDIRUSE
	rm -f ${CLEANFILES}

In diesem Beispiel führt clean das Makro _SUBDIRUSE aus, nachdem es den Befehl rm -f ${CLEANFILES} erfolgreich ausgeführt hat. Dadurch löscht clean zwar beim Wechsel in ein neues Unterverzeichnis beim Bau erstellte Dateien, aber nicht beim Wechsel aus einem Unterverzeichnis in ein übergeordnetes Verzeichnis.

7.3.2.3. Weitere Bedingungen

• exists gibt "wahr" zurück, wenn wenn die angegebene Datei bereits existiert.

• empty gibt "wahr" zurück, wenn die angegebene Variable leer ist.

• target gibt "wahr" zurück, wenn das angegebene Target noch nicht existiert.

7.3.2.4. Schleifenkonstrukte in make (.for)

.for erlaubt es, bestimmte Anweisungen für jedes Element einer Variable zu wiederholen, indem dieser Variable in jedem Durchlauf der Schleife das jeweilige Element der untersuchten Liste zugewiesen wird.

_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===> ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} && \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor

Falls das Verzeichnis SUBDIR leer ist, würde in unserem Beispiel keine Aktion erfolgen. Enthält das Verzeichnis hingegen ein oder mehrere Elemente, werden die Anweisungen zwischen .for und .endfor für jedes Element ausgeführt, wobei entry durch das jeweilige Element ersetzt werden würde.

10.1.4.1. Einrücken von Tags

Tags, die die gleiche Einrückung aufweisen wie das vorangegangene Tag, sollten durch eine Leerzeile getrennt werden, Tags mit unterschiedlicher Einrückung hingegen nicht:

<article lang='de'>
  <articleinfo>
    <title>NIS</title>

    <pubdate>October 1999</pubdate>

    <abstract>
      <para>...
	...
	...</para>
    </abstract>
  </articleinfo>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>
</article>

10.1.4.2. Gliederung von Tags

Tags wie zum Beispiel <itemizedlist>, die immer weitere Tags einschließen und selbst keine Zeichen enthalten, befinden sich immer in einer eigenen Zeile.

Tags wie <para> und <term> können selbst Text enthalten, und ihr Inhalt beginnt direkt nach dem Tag, und zwar in der gleichen Zeile.

Dies gilt analog, wenn diese zwei Tag-Arten wieder geschlossen werden.

Eine Vermischung dieser Tags kann daher zu Problemen führen.

Wenn auf ein Start-Tag, das keine Zeichen enthalten kann, unmittelbar ein Tag folgt, das andere Tags einschließen muss, um Zeichen darzustellen, befinden sich diese Tags auf verschiedenen Zeilen. Das zweite Tag wird dabei entsprechend eingerückt.

Wenn ein Tag, das Zeichen enthalten kann, direkt nach einem Tag, das keine Zeichen enthalten kann, geschlossen wird, befinden sich beide Tags in der gleichen Zeile.