Die Fibel für neue Mitarbeiter des FreeBSD-Dokumentationsprojekts
Zurück |  | Weiter

# Kapitel 4. SGML-Dokumente erstellen

In diesem Kapitel werden die beiden vom FDP eingesetzen Auszeichnungssprachen HTML und DocBook behandelt. Hierbei beschränkt sich dieses Kapitel auf die Elemente, die bei der täglichen Arbeit am ehesten zum Einsatz kommen werden.

Beide Sprachen besitzen eine große Anzahl von Elementen. Das erschwert es, das richtige Element in der richtigen Situation auszuwählen. Aus diesem Grund werden zu jedem Element auch immer Beispiele angeboten, die den richtigen Einsatz des Elements verdeutlichen sollen.

Es ist nicht das Ziel dieses Kapitels möglichst viele Elemente beider Sprachen zu behandeln – dies wäre nur eine Wiederholung der eigentlichen Sprachreferenz. Sofern es Unklarheiten zur Verwendung einzelner Elemente und Auszeichnung von bestimmten Sachverhalten gibt, können diese an FreeBSD documentation project geschickt werden.

> Fluß- kontra Blockelemente: Wenn im folgenden von Flußelementen die Rede ist, sind damit Elemente gemeint, die in einem Blockelement auftreten können und keinen Zeilenumbruch hervorrufen. Blockelemente hingegen erzeugen unter anderem einen Zeilenumbruch[1].

# 4.1. HTML

HTML, die HyperText Markup Language, ist die Auszeichnungssprache des Internets. Weitere Informationen zu HTML finden sich unter http://www.w3.org/.

Sie kommt bei der Erstellung der Webseiten des FreeBSD-Projektes zum Einsatz. Für technische Dokumentationen sollte HTML jedoch nicht eingesetzt werden, da DocBook eine größere und bessere Auswahl an Elementen bietet. Folglich sollte HTML nur für die FreeBSD-Webseiten verwendet werden.

Die HTML-Spezifikation liegt bis jetzt in mehreren Versionen vor: 1, 2, 3.0, 3.2 und (die aktuelle) 4.0. Von letzterer existieren zwei Varianten: “streng” (HTML 4.0 Strict) und “locker” (HTML 4.0 Transitional).

Die HTML-DTDs sind über den Port `textproc/html` verfügbar und werden automatisch als Teil des Metaports `textproc/docproj` mitinstalliert.

## 4.1.1. Formale Öffentliche Bezeichner

Da es mehrere Version von HTML gibt, existieren auch mehrere FÖPs, zu denen ein HTML-Dokument konform erklärt werden kann. Die Mehrzahl der sich auf der FreeBSD-Webseite befindenen HTML-Seiten sind zu der lockeren Version von HTML 4.0 konform.

    PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

## 4.1.2. Die Elemente `<head>` und `<body>`

Ein HTML-Dokument unterteilt sich normalerweise in zwei Bereiche: “head” und “body”. Der Kopf (head) enthält Metadaten wie den Dokumententitel und Angaben zum Autor. Der Rumpf (body) umfaßt den eigentlichen Dokumenteninhalt, der für den Leser bestimmt ist. In einem HTML-Dokument werden diese Bereiche über die Elemente `<head>` und `<body>` voneinander abgegrenzt. Beide sind Kinder des Wurzelelementes `<html>`.

Beispiel 4-1. Die Struktur eines HTML-Dokumentes

    <html>
      <head>
        <title>Der Dokumententitel</title>
      </head>

      <body>

        …

      </body>
    </html>

## 4.1.3. Blockelemente

### 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 `<h`N`>` stellt den Text der Überschrift dar.

Beispiel 4-2. `<h1>`, `<h2>`…

Fügen Sie in eine der existierenden Übungsdateien folgendes ein:

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

Beispiel 4-3. Falsche Verschachtelung von Überschriften

Fügen Sie in eine der existierenden Übungsdateien folgendes ein:

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

Beispiel 4-4. Absätze mit dem Element `<p>`

Fügen Sie in eine der existierenden Übungsdateien folgendes ein:

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

Beispiel 4-5. Blockzitat

Fügen Sie in eine der existierenden Übungsdateien folgendes ein:

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

Beispiel 4-6. Listen mit `<ul>` und `<ol>` erstellen

Fügen Sie in eine der existierenden Übungsdateien folgendes ein:

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

Beispiel 4-7. Definitionslisten mit `<dl>` erstellen

Fügen Sie in eine der existierenden Übungsdateien folgendes ein:

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

Beispiel 4-8. Vorformatierten Text mit `<pre>` erstellen

Der Originaltext einer E-Mail läßt sich beispielsweise wie folgt einbinden:

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

Beachten Sie, dass `<` und `&` nach wie vor als Sonderzeichen erkannt werden. Daher wird in diesem Beispiel auch `&lt;` an Stelle von `<` verwendet. Aus dem gleichen Grund wurde auch `&gt;` an Stelle von `>` verwendet. Achten Sie also stets auf Sonderzeichen, wenn Sie normalen Text aus E-Mails, Programmcode oder einer anderen Quelle kopieren.

### 4.1.3.6. Tabellen

> Anmerkung: Die meisten Textbrowser, beispielsweise Lynx, können Tabellen nicht besonders gut darstellen. Deshalb sollten Auszeichnungsalternativen in Betracht gezogen werden, um eine angemessene Darstellung sicherzustellen.

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.

Beispiel 4-9. Einfache Tabelle mit `<table>`

Fügen Sie in eine der existierenden Übungsdateien folgendes ein:

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

Beispiel 4-10. Anwendung des Attributes `rowspan`

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

Beispiel 4-11. Anwendung des Attributes `colspan`

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

Beispiel 4-12. Gemeinsame Anwendung der Attrbute `rowspan` und `colspan`

    <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. Flußelemente

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

Beispiel 4-13. Text mit `<em>` und `<strong>` hervorheben

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

Beispiel 4-14. Text mit `<b>` und `<i>` formatieren

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

Beispiel 4-15. Nicht-proportionale Schrift mit `<tt>`

    <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>` [2]. Diese Herangehensweise ist ebenfalls veraltet und sollte nicht mehr angewandt werden.

Beispiel 4-16. Schriftgröße ändern mit `<big>`, `<small>` und `<font>`

Die folgenden HTML-Schnipsel bewirken alle das gleiche:

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

> Anmerkung: Bei Links handelt es sich ebenfalls Flußelemente.

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

Beispiel 4-17. `<a href="...">` benutzen

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

Beispiel 4-18. Anwendung von `<a name="...">`

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

Beispiel 4-19. Auf einen Abschnitt eines anderen Dokumentes verweisen

Für dieses Beispiel wird davon ausgegangen, dass der mit `absatz1` gekennzeichnete Absatz sich in der HTML-Datei `foo.html` befindet.

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

### Fußnoten

[1] | Die englische Bezeichnung inline element wurde in Anlehnung an das Wort “Fließtext” mit “Flußelement” übersetzt.
[2] | Der Standardwert für `size` ist `3`.

Zurück | Zum Anfang | Weiter
Schlußbemerkung |  | Die DocBook DTD

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