# Die Fibel für neue Mitarbeiter des FreeBSD-Dokumentationsprojekts

Copyright © 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The FreeBSD Documentation Project

Copyright © 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The FreeBSD German Documentation Project

Vielen Dank für Ihr Interesse und Ihre Mitarbeit an der FreeBSD-Dokumentation. Jeder Beitrag ist für uns sehr wichtig.

In dieser Fibel wird von der eingesetzten Software bis hin zu den Vorstellungen des FreeBSD-Dokumentationsprojekts alles behandelt, was Sie wissen müssen, wenn Sie sich am FreeBSD-Dokumentationsprojekt beteiligen wollen.

Bitte beachten Sie, dass diese Fibel jederzeit unter Bearbeitung und noch nicht vollständig ist.

Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.

2. Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

> Wichtig: THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

[ einzelne Abschnitte / komplettes Dokument ]

Beispiele
1. Ein Beispiel
3-1. Verwendung eines Elements (Start- und Endtag)
3-2. Verwendung eines Elements (nur Starttag)
3-3. Verschachtelte Elemente: `<em>`
3-4. Elemente mit Attributen nutzen
3-5. Attribute mit einfachen Anführungszeichen
3-6. `.profile`, für sh(1) und bash(1) Benutzer
3-7. `.cshrc`, für csh(1)- und tcsh(1)-Benutzer
3-8. Beispiele für Kommentare in SGML
3-9. Fehlerhafte SGML-Kommentare
3-10. Allgemeine Entitäten festlegen
3-11. Parameterentitäten festlegen
3-12. Dateien mit Allgemeinen Entitäten einbinden
3-13. Dateien mit Parameterentitäten einbinden
3-14. Aufbau eines markierten Bereiches
3-15. CDATA als Inhaltsmodell für markierte Bereiche
3-16. Anwendung von `INCLUDE` und `IGNORE` in markierten Abschnitten
3-17. Kontrolle von markierten Bereichen über Parameterentitäten
4-1. Die Struktur eines HTML-Dokumentes
4-2. `<h1>`, `<h2>`...
4-3. Falsche Verschachtelung von Überschriften
4-4. Absätze mit dem Element `<p>`
4-5. Blockzitat
4-6. Listen mit `<ul>` und `<ol>` erstellen
4-7. Definitionslisten mit `<dl>` erstellen
4-8. Vorformatierten Text mit `<pre>` erstellen
4-9. Einfache Tabelle mit `<table>`
4-10. Anwendung des Attributes `rowspan`
4-11. Anwendung des Attributes `colspan`
4-12. Gemeinsame Anwendung der Attrbute `rowspan` und `colspan`
4-13. Text mit `<em>` und `<strong>` hervorheben
4-14. Text mit `<b>` und `<i>` formatieren
4-15. Nicht-proportionale Schrift mit `<tt>`
4-16. Schriftgröße ändern mit `<big>`, `<small>` und `<font>`
4-17. `<a href="...">` benutzen
4-18. Anwendung von `<a name="...">`
4-19. Auf einen Abschnitt eines anderen Dokumentes verweisen
4-20. Buchvorlage `<book>` mit `<bookinfo>`
4-21. Artikelvorlage `<article>` mit `<articleinfo>`
4-22. Ein einfaches Kapitel
4-23. Ein leeres Kapitel
4-24. Unterkapitel
4-25. Absatz mit `<para>`
4-26. `<blockquote>`
4-27. `<warning>`
4-28. `<itemizedlist>`, `<orderedlist>` und `<procedure>`
4-29. `<programlisting>`
4-30. Das `<co>`- und das `<calloutlist>`-Element
4-31. Tabellen mittels `<informaltable>` auszeichnen
4-32. Tabelle mit Attribut `frame="none"`
4-33. `<screen>`, `<prompt>` und `<userinput>`
4-34. Das Element `<emphasis>`
4-35. Richtig zitieren
4-36. Tasten, Maustasten und Tastenkombinationen
4-37. Anwendungen, Befehle und Optionen
4-38. Das Element `<filename>`
4-39. Portsnamen und das Element `<filename>`
4-40. Gerätenamen per `<devicename>` auszeichnen
4-41. `role` und `<hostid>`
4-42. Das Element `<username>`
4-43. `<maketarget>` und `<makevar>`
4-44. `<literal>`
4-45. Das Element `<replaceable>`
4-46. Das Element `<errorname>`
4-47. `<chapter>` und `<section>` mit dem Attribut `id`
4-48. Querverweise und das Element `<anchor>`
4-49. Einsatz von `<xref>`
4-50. `<link>` beutzen
4-51. Verweise mit `<ulink>`
A-1. Ein DocBook-Buch (`<book>`)
A-2. Ein DocBook-Artikel (`<article>`)
A-3. Ein DocBook-Dokument in eine einzelne HTML-Datei umwandeln
A-4. Ein DocBook-Dokument in mehrere kleine HTML-Dateien umwandeln
A-5. Ein DocBook-Dokument nach Postscript umwandeln
A-6. Eine PDF-Datei aus einem DocBook-Dokument erzeugen

# Benutzungshinweise

## Die Eingabeaufforderungen

Die folgende Tabelle zeigt die normale Eingabeaufforderung des Systems und die Eingabeaufforderung des Superusers. Die in diesem Buch vorkommenden Beispiele benutzen die jeweilige Eingabeaufforderung, um zu zeigen, unter welchem Benutzer die Beispiele ausgeführt werden sollten.

Benutzer | Eingabeaufforderung
--- | ---
`Normaler Benutzer` | `%`
`Superuser` | `#`

## Typographische Festlegungen

Um die Lesbarkeit zu erhöhen, werden in diesem Dokument die im folgenden genannten typographischen Festlegungen verwendet:

Bedeutung | Beispiel
--- | ---
Kommandonamen | Geben Sie `ls -a` ein, um alle Dateien anzuzeigen.
Datei- und Verzeichnisnamen | Bearbeiten Sie die Datei `.login`.
Bildschirmein- und ausgaben |
    You have mail.
Referenzen auf Hilfeseiten | Mit su(1) können Sie sich als ein anderer Benutzer anmelden.
Benutzer- und Gruppennamen | Ich bin `root`, ich darf das.
Hervorhebungen | Hier müssen Sie vorsichtig sein.
Argumente auf der Kommandozeile, die durch existierende Namen, Dateien oder Variablen ersetzt werden müssen | Dateien können Sie mit dem Befehl `rm ``Dateiname``` löschen.
Umgebungsvariablen | `$HOME` ist Ihr Benutzerverzeichnis.

## Anmerkungen, Tips, wichtige Hinweise, Warnungen und Beispiel

An einigen Stellen innerhalb dieses Buchs werden wichtige oder nützliche Hinweise gegeben, die besonders hervorgehoben sind. Hier ein kurzer Überblick über die verwendeten Darstellungen.

> Anmerkung: Anmerkungen werden so dargestellt. Sie enthalten Informationen die Sie nur zu lesen brauchen, wenn Sie direkt davon betroffen sind.

> Tipp: Tipps sind Informationen, die vielleicht hilfreich sein könnten oder aufzeigen, wie bestimmte Dinge einfacher zu bewerkstelligen sind.

> Wichtig: Besonders wichtige Punkte werden so hervorgehoben. Meist enthalten sie Hinweise auf vielleicht zusätzlich auszuführende Schritte oder Dinge, die besonders zu beachten sind.

> Warnung: Warnungen werden wie dieser Abschnitt dargestellt und weisen auf mögliche Schäden hin, die entstehen können, falls die beschriebenen Schritte nicht genau befolgt oder Hinweise nicht beachtet werden. Die Palette der möglichen Schäden reicht von Hardwareschäden bis hin zu Datendatenverlust durch ein versehentliches Löschen von wichtigen Dateien oder ganzen Verzeichnissen.

Beispiel 1. Ein Beispiel

Beispiele, die so wie hier dargestellt werden, enthalten meist kleine Übungen, die nachvollzogen werden sollten, um das vorher beschriebene besser zu verinnerlichen oder mit den erzeugten Ausgaben vertraut zu werden.

## Danksagungen

Ich möchte mich bei Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn und Christopher Maden bedanken, die sich die Zeit genommen haben, die frühen Entwürfe dieses Dokuments zu lesen und viele hilfreiche Hinweise und Ratschläge gegeben haben.

# Kapitel 1. Überblick

Herzlich Willkommen beim FreeBSD-Dokumentationsprojekt. Qualitativ hochwertige Dokumentation ist ein wichtiger Erfolgsfaktor und sehr bedeutend für die Verbreitung von FreeBSD. Die wichtigste Quelle dafür ist das FreeBSD-Dokumentationsprojekt (FDP). Jeder Beitrag, der zu diesem Projekt geleistet wird, ist ungemein wertvoll.

Es ist das Anliegen dieser Fibel, den Leser mit dem FDP vertraut zu machen und zu erklären, wie das FDP organisiert ist, wie man selber Dokumente erstellt und an das FDP einreicht und wie die verfügbaren Werkzeuge effektiv beim Schreiben eingesetzt werden können.

Wie jedes Opensourceprojekt, ist auch das FDP auf die Mithilfe vieler angewiesen. Deshalb ist jeder herzlich eingeladen mitzuarbeiten. Die dafür erforderlichen Voraussetzungen sind gering und es gibt keine Verpflichtung eine bestimmte Menge an Dokumenten pro Monat oder Jahr beizusteuern. Das Einzige, was Sie tun müssen, ist sich auf der Mailingliste FreeBSD documentation project einzutragen.

Nach dem Lesen der FDP-Fibel sollte man wissen:

- welche Dokumente durch das FDP betreut werden,

- wie man SGML-Dokumente liest und den SGML-Quellcode der durch das FDP betreuten Dokumente versteht,

- wie man selbst Änderungen an Dokumenten vornehmen kann und

- wie man Änderungen zur Begutachtung durch das FDP einreichen kann.

## 1.1. Die FreeBSD-Dokumentationsreihe

Das FDP umfaßt vier verschiedene Kategorien:

Hilfeseiten

  Die englischen Hilfeseiten wurden nicht vom FDP geschrieben, da sie ein Teil des Basissystems sind. Jedoch können bzw. wurden bereits Teile von existierenden Hilfeseiten umformuliert, um sie verständlicher zu machen oder um Fehler zu beheben.

  Für die Übersetzung der Hilfeseiten des Systems in die verschiedenen Sprachen sind die einzelnen Übersetzergruppen verantwortlich. Alle dabei entstandenen Übersetzungen gehören zum FDP.

Die FAQ

  Das Ziel der FAQ ist es, Fragen, die auf den verschiedenen Maillinglisten und in Newsgruppen regelmäßig diskutiert werden, nach einem einfachen Frage- und Antwort-Muster zu behandeln. Das schließt nicht aus, das auf bestimmte Fragen ausführlich und umfassend eingegangen wird.

Das Handbuch

  Das Ziel des Handbuches ist es, die umfassende Quelle und Referenz im Netz für FreeBSD-Benutzer zu sein.

Die Webseite

  Die Webseite http://www.FreeBSD.org und ihre vielen Spiegel auf der ganzen Welt vertreten das FreeBSD-Projekt im WWW. Für viele Menschen ist sie der erste Kontakt mit FreeBSD.

Jede dieser vier Kategorien wird im FreeBSD-CVS-Baum verwaltet. Das bedeutet, dass alle Änderungen an den Dateien für jeden verfügbar sind und jeder sich mittels eines Programms wie CVSup oder CTM eine lokale Kopie der Dokumentation anlegen kann.

Parallel zum FDP haben viele Menschen Anleitungen geschrieben und Webseiten mit Bezug zu FreeBSD erstellt. Einige davon werden im CVS-Archiv verwaltet, sofern der Autor dem zugestimmt hat. In anderen Fällen hat sich der Autor entschlossen, seine Dokumentation außerhalb des zentralen FreeBSD-CVS-Archivs zu verwalten. Das FDP bemüht sich, so viele Verweise wie möglich auf solche Quellen bereitzustellen.

## 1.2. Bevor es losgeht

Zum Verständnis der folgenden Kapitel sollte folgendes bereits bekannt sein:

- Wie eine aktuelle Kopie der FreeBSD-Dokumentation entweder auf Basis des FreeBSD-CVS-Archivs mittels CVS, CTM oder CVSup angelegt und gepflegt wird, oder wie mit CVSup eine frische Kopie des CVS-Archivs heruntergeladen wird.

- Wie neue Programme mit Hilfe des FreeBSD-Portsystems oder mittels pkg_add(1) heruntergeladen und installiert werden.

## 1.3. Der Schnellstart

Falls man einfach loslegen möchte und sich sicher genug fühlt, um alles weitere erst bei Bedarf nachzusehen, kann man einfach den folgenden Anweisungen folgen:

1. Zuerst muß der Metaport `textproc/docproj` auf dem betreffenden Arbeitsrechner installiert werden.

       # cd /usr/ports/textproc/docproj
       # make JADETEX=no install

2. Anschließend sollte eine lokale Kopie des FreeBSD-`doc`-Verzeichnisbaumes angelegt werden. Hierfür kann man entweder auf CVSup im `checkout`-Modus zurückgreifen oder mittels cvs eine komplette Kopie des CVS-Archivs anlegen.

   Wenn man lieber mit einer Kopie des CVS-Archivs arbeiten möchte, werden als Minimum die Verzeichnisse `doc/share` und `doc/de_DE.ISO8859-1/share` benötigt.

       % cvs checkout doc/share
       % cvs checkout doc/de_DE.ISO8859-1/share

   Für den Fall, dass ausreichend Platz auf der Festplatte vorhanden ist, kann auch eine eine vollständige Arbeitskopie des gesamten CVS-Baumes anlegt werden.

       % cvs checkout doc

3. Sollte geplant sein, ein existierendes Buch oder einen existierenden Artikel zu ändern, muß natürlich noch zusätzlich das betreffende Verzeichnis aus dem CVS-Archiv geholt werden. Soll hingegen ein neues Buch oder ein neuer Artikel geschrieben werden, empfiehlt es sich, auf bestehende Bücher und Artikel zurückzugreifen und diese als Vorlage zu nutzen.

   Ein Artikel über die Konfiguration eines VPNs zwischen FreeBSD und Windows 2000 kann wie folgt erstellt werden:

   1. Zuerst wird das Verzeichnis `articles` aus dem FreeBSD-CVS-Archiv lokal angelegt:

          % cvs checkout doc/de_DE.ISO8859-1/articles

   2. Anschließend kopiert man einen bereits existierenden Artikel und nutzt ihn als Vorlage. In diesem Beispiel soll der neue Artikel im Verzeichnis `vpn-w2k` liegen:

          % cd doc/de_DE.ISO8859-1/articles
          % cp -R committers-guide vpn-w2k

   Bereits exisitierende Dokumente, die geändert werden sollen, können direkt aus dem CVS-Archiv geholt werden. Das folgende Beispiel zeigt das für die FAQ aus dem Verzeichnis `doc/de_DE.ISO8859-1/books/faq`:

       % cvs checkout doc/de_DE.ISO8859-1/books/faq

4. Jetzt können die `.sgml` Dateien mit einem beliebigen Texteditor bearbeitet werden.

5. Danach ist `make` mit dem Ziel `lint` aufzurufen, um das gesamte Dokument auf Auszeichnungsfehler hin zu untersuchen, ohne dass zeitaufwändige Transformationen vorgenommen werden.

       % make lint

   Soll anschließend das Zieldokument erstellt werden, kann mit Hilfe der Variable `FORMATS` bestimmt werden, welche Ausgabeformate erzeugt werden sollen. Unterstützt werden momentan `html`, `html-split`, `txt`, `ps`, `pdf` und `rtf`. Die aktuelle Liste der unterstützten Formate befindet sich am Anfang der Datei `doc/share/mk/doc.docbook.mk`. Bei der Verwendung dieser Variable ist es wichtig, darauf zu achten, dass die Angabe der gewünschten Formate in Anführungszeichen eingeschlossen wird, sofern mehr als nur ein Format gleichzeitig erstellt werden soll.

   Wenn das Dokument beispielsweise nach `HTML` konvertiert werden soll, kann dies so vorgenommen werden:

       % make FORMATS=html

   Soll es hingegen in den Formaten `html` und `txt` erzeugt werden, kann man entweder make(1) zweimal hintereinander aufrufen:

       % make FORMATS=html
       % make FORMATS=txt

   oder beide Formate mit einem Aufruf von make(1) erzeugen:

       % make FORMATS="html txt"

6. Zum Schluß müssen die Änderungen an das FDP mittels send-pr(1) eingesandt werden.

# Kapitel 2. Die Werkzeuge

Innerhalb des FDPs werden verschiedene Programme für die Verwaltung der FreeBSD-Dokumentation, ihrer Transformation in verschiede Formate und weitere Aufgaben eingesetzt. Wer an der FreeBSD-Dokumentation mitarbeiten möchte, wird diese Programme benötigen.

Doch dies ist kein Grund zur Angst, da alle notwendigen Programme als FreeBSD-Ports und fertige Pakete vorhanden sind, wodurch sich die Installation drastisch vereinfacht.

Allerdings müssen diese Programme installiert werden, bevor alle Beispiele der folgenden Kapitel ausprobiert werden können.

> Wenn es möglich ist, sollte der Port `textproc/docproj` verwendet werden: Durch die Installation des Ports `textproc/docproj` kann die Installation vereinfacht und eine Menge Zeit gespart werden. Bei diesem Port handelt es sich um einen Metaport, der selbst keine Programme oder ähnliches installiert. Stattdessen enthält er eine Vielzahl von Abhängigkeiten zu anderen Ports und setzt deren korrekte Installation voraus. Durch seine Installation sollten automatisch alle Pakete, die in diesem Kapitel genannt werden, auf den Rechner geladen und dort installiert werden.

> Ein nur unter bestimmten Umständen benötigter Port ist das JadeTeX-Makro-Paket, das seinerseits eine TeX-Installation voraussetzt. TeX ist ein ziemlich großes Programmpaket und sollte nur installiert werden, sofern Zieldokumente im PostScript- oder PDF-Format generiert werden sollen.

> Um den Platz und die Zeit für die Installation von JadeTeX und TeX zu sparen, muß bei der Installation angeben werden, ob JadeTeX (und damit auch TeX) installiert werden soll oder nicht.

> Daher sollte der docproj-Port entweder mit

>     # make JADETEX=yes install

> oder mit

>     # make JADETEX=no install

> installiert werden, je nachdem was gewünscht wird. Alternativ können Sie auch direkt die Ports `textproc/docproj-jadetex` oder `textproc/docproj-nojadetex` installieren. Die Variable `JADETEX` wird von diesen Ports automatisch entsprechend gesetzt. Ohne JadeTeX können Sie nur die Formate HTML und ASCII erzeugen. Die Formate PostScript und PDF erfordern TeX.

## 2.1. Notwendige Werkzeuge

### 2.1.1. Software

Die folgenden Programme sind notwendig, um sinnvoll an der FreeBSD-Dokumentation arbeiten und diese in andere Formate wie HTML, reinen Text und RTF umwandeln zu können. Sie müssen diese aber nicht seperat installieren, da alle Programme automatisch durch den Metaport `textproc/docproj` installiert werden.

Jade (`textproc/jade`)

  Eine DSSSL-Implementierung. Sie wird gebraucht, um Dokumente in andere Formate wie HTML und TeX zu übersetzen.

Tidy (`www/tidy`)

  Ein Formatierer, mit dem man Teile der automatisch generierten HTML-Dateien neuformatieren kann, um ihre Lesbarkeit zu erhöhen.

Links (`www/links`)

  Ein Textbrowser, der HTML-Dateien in einfache Textdateien umwandeln kann.

peps (`graphics/peps`)

  Einige der Dokumente enthalten Grafiken, die nur im EPS-Format vorliegen. Damit diese von dem meisten Webbrowsern angezeigt werden können, müssen sie nach PNG konvertiert werden.

### 2.1.2. Die DTDs und die Entitäten

Das FDP benutzt verschiedene DTDs und Entitätensätze, die installiert sein müssen, bevor mit der Arbeit an einem beliebigen Dokument begonnen werden kann.

HTML DTD (`textproc/html`)

  HTML ist die bevorzugte Auszeichnungssprache des World Wide Web und wird durchgängig für die FreeBSD-Webseite genutzt.

DocBook DTD (`textproc/docbook`)

  DocBook ist als Auszeichnungssprache für technische Dokumentationen entwickelt worden. Die gesamte FreeBSD-Dokumentation wird mittels DocBook erstellt.

ISO 8879-Entitäten (`textproc/iso8879`)

  19 der ISO 8879:1986-Zeichensätze, die von vielen DTDs benötigt werden. Darin enthalten sind mathematische Symbole, zusätzliche Zeichen, die für auf dem lateinischen beruhende Alphabete benötigt werden sowie griechische Zeichen.

### 2.1.3. Die Stilvorlagen

Die Stilvorlagen werden während der Transformation und der Formatierung von Dokumenten, beispielsweise für die Bildschirmdarstellung oder den Druck, benutzt.

Modular DocBook Stylesheets (`textproc/dsssl-docbook-modular`)

  Die Modular DocBook Stylesheets werden benötigt, wenn mittels DocBook erstellte Dokumente in Formate wie HTML oder RTF konvertiert werden sollen.

## 2.2. Optionale Werkzeuge

Die in diesem Kapitel genannten Programme müssen nicht unbedingt installiert werden. Allerdings können sie die Arbeit an der Dokumentation erleichtern und die Anzahl an möglichen Ausgabeformaten erhöhen.

### 2.2.1. Software

JadeTeX und teTeX (`print/jadetex` und `print/teTeX`)

  Jade und teTeX werden eingesetzt, um DocBook-Dokumente nach DVI, Postscript und PDF zu konvertieren. Hierfür müssen die JadeTeX Makros installiert sein.

  Ist es nicht geplant, die Dokumente in einem dieser Formate zu erzeugen, wenn also HTML, Text und RTF ausreichend sind, brauchen JadeTeX und teTeX nicht installiert zu werden. Da die Installation von teTeX insgesamt 30 MB benötigt, kann so Zeit und Plattenplatz gespart werden.

  > Wichtig: Wird sich für die Installation von JadeTeX und teTeX entschieden, muß teTeX anschließend noch eingerichtet werden. Die Datei `print/jadetex/pkg-message` enthält detailierte Angaben zu den dafür notwendigen Schritten.

Emacs oder XEmacs (`editors/emacs` oder `editors/xemacs`)

  Beide Texteditoren haben einen speziellen Modus zur Bearbeitung von SGML-Dokumenten entsprechend den Vorgaben einer SGML-DTD. Zusätzlich bieten sie Funktionen an, mit denen sich der Tippaufwand reduzieren und Fehlerwahrscheinlichkeit senken läßt.

  Natürlich muß nicht mit einem dieser Texteditoren gearbeitet werden; jeder andere Editor kann dafür genausogut genutzt werden, doch vielleicht wird die Arbeit durch sie als effektiver empfunden werden.

Sofern Sie Vorschläge haben, welche andere Software für die Verarbeitung oder Bearbeitung von SGML-Dokumenten in diese Liste mitaufgenommen werden sollte, senden Sie diese bitte an Documentation Engineering Team `<doceng@FreeBSD.org>`.

# Kapitel 3. Die SGML-Fibel

Die Mehrzahl der Dokumente des FDPs sind in SGML geschrieben. Ziel dieses Kapitels ist es, genau zu erklären, was das bedeutet und wie man die SGML-Quellen liest und versteht. Ebenso werden die in den Quellen genutzten Kniffe erklärt, auf die man beim Lesen der Dokumente stoßen wird.

Teile dieses Kapitels basieren auf Mark Galassis Get Going With DocBook.

## 3.1. Überblick

In den guten alten Zeiten war der Umgang mit elektronischem Text einfach. Man musste lediglich wissen, welcher Zeichensatz (ASCII, EBCDIC oder ein anderer) vorlag. Text war einfach Text und sah so aus, wie man ihn sah. Keine Extras, keine Formatierungen und kein sonstiger Schnickschnack.

Für viele Zwecke war dies allerdings nicht ausreichend. Von einem machinenlesbaren Text wird erwartet, dass er auch von Maschinen gelesen und intelligent weiterverarbeitet werden kann. Einzelne Stellen sollen hervorgehoben werden, andere sollen in ein Glossar aufgenommen werden oder auf andere Textstellen verweisen. Dateinamen wiederum sollen in einer schreibmaschinenähnlichen Schrift auf dem Bildschirm dargestellt werden, der Ausdruck soll jedoch in Schrägschrift oder in einer beliebigen anderen Darstellungsform erfolgen.

Anfänglich gab es die Hoffnung, dass die Künstliche Intelligenz (KI) helfen würde, dieses Ziel zu erreichen. Computer sollte den Text lesen und dazu in der Lage sein, selbstständig wichtige Formulierungen, Dateinamen, Benutzereingaben oder Beispiele zu erkennen. Leider verlief die Entwicklung in diesem Bereich nicht wie gewünscht und Computer benötigen nach wie vor etwas Unterstützung, bevor sie Texte vernünftig verarbeiten können.

Genauer gesagt, man muss ihnen sagen, was was ist. Sehen wir uns folgende Zeilen an:

> Löschen Sie `/tmp/foo` mittels rm(1).

>     % rm /tmp/foo

Es fällt uns leicht, zu erkennen, was ein Dateiname, ein einzugebender Befehl oder ein Verweis auf eine Hilfeseite ist. Das kann ein Computer, der einen Text verarbeitet, nicht. Aus diesem Grund ist es notwendig, Texte mit weiteren Informationen auszuzeichnen.

Der Begriff Auszeichnung[1] bedeutet, dass sich der Wert eines Textes erhöht, aber auch seine Kosten. Durch Auszeichnungen wird einem Dokument zusätzlicher Text hinzugefügt, der aber von dem eigentlichen Dokumenteninhalt auf eine bestimmte Art und Weise unterschieden werden kann, so dass Programme die Auszeichnung erkennen können und mittels dieser Informationen während der Verarbeitung in der Lage sind, Entscheidungen zu treffen. Texteditoren können diese Auszeichnungselemente vor dem Benutzer verbergen, um zu vermeiden, dass er durch sie abgelenkt wird.

Die durch die Auszeichnungselemente im Textdokument zusätzlich abgelegten Informationen erhöhen den Wert des Dokuments. Allerdings muss diese Arbeit in den meisten Fällen von einem Menschen getan werden - wären Maschinen dazu fähig, wären zusätzliche Auszeichnungselemente unnötig. Der damit verbundene Aufwand erhöht die Kosten, die durch die Erstellung des Dokuments entstehen.

Das etwas weiter oben gegebene Beispiel sieht im Quelltext so aus:

    <para>Löschen Sie <filename>/tmp/foo</filename> mittels <citerefentry/<refentrytitle/rm/<manvolnum/1//.</para>

    <screen><prompt>%</prompt> <userinput>rm /tmp/foo</userinput></screen>

Die Auszeichnungselemente sind deutlich vom eigentlichen Inhalt zu unterscheiden.

Die Einführung von Auszeichnungselementen setzt voraus, dass festgelegt wird, welche Bedeutung einzelne Elemente haben und wie diese interpretiert werden. Sie brauchen daher eine Auszeichnungssprache, der Sie folgen, wenn Sie eigene Dokumente verfassen.

Natürlich kann es keine universelle Auszeichnungssprache geben und eine einzige mag nicht ausreichend für alle möglichen Anwendungsfälle sein. Eine Sprache für technische Dokumente wird sich wahrscheinlich stark von einer für Kochrezepte unterscheiden. Die universelle Lösung ist eine Basissprache, mit deren Hilfe weitere Sprachen entwickelt werden können - eine Meta-Auszeichungssprache also.

Genau diese Anforderung wird von der Standard Generalized Markup Language (SGML) erfüllt. Mit ihrer Hilfe wurden viele andere Auszeichungssprachen wie beispielsweise HTML und DocBook, welche beide von FDP genutzt werden, entwickelt.

Die eigentliche Sprachdefinition erfolgt in einer Dokumenten-Typ-Definition (DTD). Innerhalb dieser DTD werden die Namen der einzelnen Elemente, deren mögliche Reihenfolge und Verschachtelung sowie weitere Informationen festgelegt.

Eine DTD ist eine vollständige Definition aller möglichen Sprachelemente, ihrer Reihenfolge[2], optionaler Elemente und so weiter und so weiter. Dank dieser recht formalen Festlegung ist es möglich, SGML-Parser zu entwickeln, die sowohl ein Dokument als auch seine DTD einlesen und anhand dieser DTD prüfen können, ob das Dokument allen Anforderungen der DTD entspricht. Dieser Vorgang wird allgemein als Validierung des Dokuments bezeichnet.

> Anmerkung: Das Validieren eines SGML-Dokuments gegen eine DTD überprüft lediglich die korrekte Syntax des Dokuments, dass heißt, ob nur gültige Auszeichnungselemente verwendet wurden und ihre Reihenfolge stimmt. Dabei wird nicht geprüft, ob die Elemente der DTD sinngemäß verwandt wurden. Sollten beispielsweise alle Dateinamen als Funktionsnamen ausgezeichnet worden sein, so würde der Parser keinen Fehler signalisieren. Formaler ausgedrückt: Der Parser prüft die Syntax, aber nicht die Semantik.

Es ist anzunehmen, dass, wenn man selber vor hat Dokumentation für das FDP zu schreiben, der größte Teil davon mit Hilfe von HTML oder DocBook geschrieben werden wird. Aus diesem Grunde wird an dieser Stelle nicht erklärt, wie eine DTD entwickelt wird.

## 3.2. Von Elementen, Tags und Attributen

Alle in SGML geschriebenen DTDs haben bestimmte gemeinsame Eigenschaften. Das ist nicht verwunderlich, da sich die hinter SGML stehende Idee unweigerlich bemerkbar macht. Zwei der markantesten Merkmale dieser Idee sind die Begriffe Inhalt und Element.

Von einem Dokument, unabhängig, ob es sich um eine einzelne Webseite oder ein langes Buch handelt, wird angenommen, dass es einen wie auch immer gearteten Inhalt hat. Dieser lässt sich selbst wiederum in Teilelemente aufspalten, die ebenso zerlegbar sind. Durch die Aufnahme von Auszeichnungselementen in einen Text, werden diese einzelnen Elemente eindeutig benannt und voneinander abgegrenzt.

Nimmt man zum Beispiel ein typisches Buch, so kann man es auf der obersten Ebene als ein Ganzes, als ein Element betrachten. Dieses Buch-Element enthält nun Kapitel, die wiederum selbst als Elemente bezeichnet werden können. Jedes einzelne Kapitel enthält weitere Elemente. So gibt es beispielsweise Absätze, Zitate und Fußnoten. Jeder Absatz kann wiederum selbst Elemente enthalten, die helfen, den Absatzinhalt als direkte Rede oder als Namen eines der Protagonisten einer Geschichte zu identifizieren.

Wenn man möchte, kann man sich das als Unterteilung[3] des Inhalts vorstellen. Auf der obersten Ebene gibt es ein Element: das Buch selbst. Schaut man ein wenig tiefer, findet man weitere Teilelemente: die einzelnen Kapitel. Diese sind wiederum unterteilt in Absätze, Fußnoten, Namen und so weiter und so weiter.

Anzumerken ist an dieser Stelle, dass das eben gesagte ohne weiteres auf jeden Inhaltstyp angewandt werden kann, auch ohne dass von SGML die Rede ist. Man könnte beispielsweise einfach verschiedene Stifte nehmen und einen Ausdruck dieser Fibel vor sich hinlegen und dann mit verschiedenen Farben die einzelnen Abschnitte des Buchinhalts markieren.

Leider gibt es keinen elektronischen Stift, um das zu tun. Deshalb muss ein anderer Weg gewählt werden, um zu bestimmen, zu welchem Element die einzelnen Inhalte gehören. In SGML-basierten Auszeichnungssprachen wie HTML und DocBook werden dafür so genannte Tags eingesetzt.

Mit einem solchen Tag wird eindeutig festgelegt, wo ein bestimmtes Element beginnt und wo es endet. Allerdings gehört der Tag selber nicht zum Element. Er legt lediglich die Grenzen des Elements fest. Da jede DTD mit dem Ziel entwickelt wurde, einen speziellen Inhaltstyp auszuzeichnen, wird jede DTD verschiedene Elemente kennen, die daher natürlich auch unterschiedlich benannt sein werden.

Der Starttag für ein imaginäres Element mit dem Namen `elementname` ist `<<`elementname`>>`. Sein Gegenstück, der schließende Endtag, ist `<</`elementname`>>`.

Beispiel 3-1. Verwendung eines Elements (Start- und Endtag)

HTML kennt das Element `<p>`, um festzulegen, dass ein bestimmter abgegrenzter Bereich einen Absatz darstellt. Dieses Element hat sowohl einen Start- als auch einen Endtag.

    <p>Das ist ein Absatz. Er beginnt mit Starttag
      für das Element 'p' und endet mit dem Endtag für
      das Element 'p'.</p>

    <p>Das ist ein etwas kürzerer Absatz.</p>

Elemente müssen nicht notwendigerweise einen Endtag haben. Ebenso ist es nicht notwendig, dass Elemente einen Inhalt haben. Beispielsweise kann in HTML-Dokumenten mittels eines speziellen Elements festgelegt werden, dass eine horizontale Linie an einer bestimmten Stelle erscheinen soll. Da dieses Element offensichtlich keinen Inhalt hat, wird auch kein Endtag benötigt.

Beispiel 3-2. Verwendung eines Elements (nur Starttag)

In HTML kann man mit dem Element `<hr>` festlegen, dass an einer bestimmten Stelle eine horizontale Linie angezeigt werden soll. Da dieses Element keinen Inhalt umschließt, hat es nur einen Starttag.

    <p>Das ist ein Abschnitt.</p>

    <hr>

    <p>Das ist ein weiterer Absatz. Eine horizontale Linie
      trennt ihn vom vorherigen Absatz.</p>

Elemente können andere Elemente enthalten. Im anfangs erwähnten Buch enthielt das Buch-Element alle Kapitel-Elemente, die wiederum alle Absatz-Elemente enthielten und so fort.

Beispiel 3-3. Verschachtelte Elemente: `<em>`

    <p>Das ist ein einfacher <em>Abschnitt</em>, in dem
      einige <em>Worte</em> <em>hervorgehoben</em> wurden.

Welche Elemente andere Elemente enthalten können und welche das sind, wird innerhalb der DTD eines Dokuments festgelegt.

> Wichtig: Viele Leute sind oft verwirrt, wenn es um die richtige Benutzung der Begriffe Tag und Element geht. Im Ergebnis werden sie oft so genutzt, als wären sie austauschbar. Allerdings sind sie das nicht.

> Ein Element ist ein konzeptioneller Teil eines Dokuments und hat einen festgelegten Anfang und ein festgelegtes Ende. Ein Tag hingegen markiert die Stelle, an der ein Element beginnt und endet.

> Wenn in diesem Dokument vom Tag `<p>` gesprochen wird, ist damit der Text gemeint, der aus den drei Zeichen `<`, `p` und `>` besteht. Wird hingegen von dem Element `<p>` gesprochen, ist damit das gesamte Element gemeint.

> Diese Unterscheidung ist sicherlich subtil. Trotzdem sollte man sie sich vergegenwärtigen.

Elemente können selber Attribute haben, die aus einem Namen und einem Wert bestehen. Die Attribute haben die Aufgabe, dem Element zusätzliche Informationen hinzuzufügen. Denkbar sind hier Festlegungen über die Darstellung, Bezeichner, über die das Element eindeutig identifiziert werden kann, oder beliebige andere Informationen.

Elementattribute werden in den Starttag eingefügt und haben die Form ``Attributename`="`Wert`"`.

Bei einigen HTML-Versionen kennt das Element `<p>` das Attribut `<align>`, mit dessen Hilfe die Textausrichtung eines Absatzes bestimmt werden kann.

`align` akzeptiert einen von vier vorgegebenen Werten: `left`, `center`, `right` und `justify`. Ist `align` nicht angegeben, wird vom Standardwert `left` ausgegangen.

Beispiel 3-4. Elemente mit Attributen nutzen

    <p align="left">Die Verwendung des align-Attributs
      für diesen Absatz ist überflüssig, da left
      der Standardwert ist.</p>

    <p align="center">Dieser Absatz wird hoffentlich mittig dargestellt.</p>

Einige Attribute akzeptieren nur bestimmte Werte, wie beispielsweise `left` oder `justify`. Andere akzeptieren jeden beliebigen Wert. Enthält Attributwert doppelte Anführungszeichen (`"`), wird der Wert in einfachen Anführungszeichen eingeschlossen.

Beispiel 3-5. Attribute mit einfachen Anführungszeichen

    <p align='right'>Ich stehe rechts!</p>

Manchmal können die Anführungszeichen um den Attributwert weggelassen werden. Allerdings sind die Regeln, die festlegen wann dies zulässig ist, sehr spitzfindig. Am besten schließen Sie Attributwerte immer in Anführungszeichen ein.

Die Informationen über Attribute, Elemente und Tags sind in SGML-Katalogen abgelegt und werden von den verschiedenen Werkzeugen des Dokumentationsprojektes genutzt, um die geschriebenen Dokumente zu validieren. Die Programme die durch `textproc/docproj` installiert werden, bringen ihre eigenen Katalogvarianten mit, zudem pflegt das FDP seine eigenen Kataloge. Beide Katalogarten müssen von allen Programmen gefunden werden können.

### 3.2.1. Was dafür getan werden muss;...

Damit die Beispiele dieser Fibel ausgeführt werden können, ist es notwendig, dass einige Programme auf dem Rechner installiert sind und das eine Umgebungsvariable korrekt gesetzt wird.

1. Der erste Schritt ist die Installation des Ports `textproc/docproj` über das FreeBSD-Portsystem. `textproc/docproj` ist ein Metaport, der alle vom FDP benötigten Programme und Daten aus dem Netz laden und installieren sollte.

2. Anschließend muss in den Shellkonfigurationsdateien die Variable `SGML_CATALOG_FILES` [4] gesetzt werden.

   Beispiel 3-6. `.profile`, für sh(1) und bash(1) Benutzer

       SGML_ROOT=/usr/local/share/sgml
       SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
       SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
       SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
       SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
       SGML_CATALOG_FILES=/usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
       SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES
       export SGML_CATALOG_FILES

   Beispiel 3-7. `.cshrc`, für csh(1)- und tcsh(1)-Benutzer

       setenv SGML_ROOT /usr/local/share/sgml
       setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
       setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
       setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
       setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
       setenv SGML_CATALOG_FILES /usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
       setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES
       setenv SGML_CATALOG_FILES /usr/doc/de_DE.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES

   Damit die Änderungen wirksam werden, meldet man sich ab und anschließend wieder an - oder man führt die obigen Anweisungen direkt in der Shell aus und setzt so die benötigten Umgebungsvariablen.

1. Nun sollte man eine Datei `beispiel.sgml` anlegen, die den folgenden Text enthält:

       <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

       <html>
         <head>
           <title>Eine Beispieldatei in HTML</title>
         </head>

         <body>
           <p>Das ist ein Absatz mit etwas Text.</p>

           <p>Das ist ein Absatz mit anderem Text.</p>

           <p align="right">Dieser Absatz wird rechtsbündig
             ausgerichtet.</p>
         </body>
       </html>

2. Nachdem die Datei abgespeichert wurde, kann sie mit Hilfe eines SGML-Parsers validiert werden.

   Bestandteil von `textproc/docproj` ist `onsgmls` - ein validierender Parser. `onsgmls` liest ein Dokument entsprechend einer SGML-DTD ein und gibt anschließend ein Element-Structure-Information-Set (ESIS) aus. Allerdings ist das an dieser Stelle nicht weiter wichtig.

   Wird `onsgmls` mit der Option `-s` aufgerufen, werden nur Fehlermeldungen ausgegeben. Dadurch kann leicht geprüft werden, ob ein Dokument gültig ist oder nicht.

   So prüft man mit `onsgmls`, ob die neuangelegte Beispieldatei gültig ist:

       % onsgmls -s beispiel.sgml

   Sofern das Beispiel korrekt abgetippt wurde, wird sich `onsgmls` ohne jegliche Ausgabe beenden. Das bedeutet, dass das Dokument erfolgreich validiert werden konnte und somit gültig ist.

3. Jetzt sollten die Tags `<title>` und `</title>` aus dem Dokument gelöscht und das Dokument erneut validiert werden:

       % onsgmls -s beispiel.sgml
       onsgmls:beispiel.sgml:5:4:E: character data is not allowed here
       onsgmls:beispiel.sgml:6:8:E: end tag for "HEAD" which is not finished

   Die Fehlermeldungen, die von `onsgmls` ausgegeben werden, sind in durch Doppelpunkte getrennte Spalten unterteilt.

   Spalte | Bedeutung
   --- | ---
   1 | Der Name des Programms, das den Fehler meldet. Hier wird immer `onsgmls` stehen.
   2 | Der Name der fehlerhaften Datei.
   3 | Die Zeilennummer des Fehlers.
   4 | Die Spaltenummer des Fehlers.
   5 | Ein einbuchstabiger Code, der über die Art des Fehlers informiert. `I` steht für eine informelle Meldung, `W` für eine Warnung und `E` für Fehler[a] und `X` für einen Querverweis. Bei den oben stehenden Ausgaben handelt es sich also um Fehlermeldungen.
   6 | Die Meldung.
   Bemerkungen: a. Nicht immer besteht eine Meldung aus fünf Spalten. Die Ausgabe von `onsgmls -sv` ist beispielsweise `onsgmls:I: SP version "1.3"` (natürlich abhängig von der Version). Wie man sehen kann, handelt es sich hier um eine informelle Meldung.

   Durch das Weglassen des Tags `<title>` sind zwei unterschiedliche Fehler entstanden.

   Der erste Fehler besagt, dass Inhalt (in diesem Falle Zeichen anstatt eines Starttags) an einer Stelle gefunden wurde, an der der Parser etwas anderes erwartet hat. Genauer gesagt wurde der Starttag eines Elements erwartet, das innerhalb von `<head>` auftreten kann.

   Der zweite Fehler wurde dadurch verursacht, dass das Element `<head>` ein Element `<title>` enthalten muss und `onsgmls` nicht berücksichtigt, dass dieser Fehler auf dem vorhergehenden beruht. Es wird lediglich festgestellt, dass der Endtag von `<head>` auftritt, obwohl nicht alle notwendigen Elemente vorhanden sind.

4. Zum Schluß sollte der Tag `<title>` wieder in die Beispieldatei eingefügt werden.

## 3.3. Die DOCTYPE-Deklaration

Am Anfang jedes Dokuments muss der Name der dem Dokument zugrundeliegenden DTD angegeben werden. Mit Hilfe dieser Information können SGML-Parser die verwendete DTD feststellen und prüfen, ob das Dokument zu ihr konform ist.

Üblicherweise steht diese Information in einer Zeile, die als DOCTYPE-Deklaration bezeichnet wird.

Eine Deklaration für ein HTML-Dokument, das nach den Vorgaben der DTD für HTML 4.0 geschrieben wurde, sieht so aus:

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">

und besteht aus verschiedenen Teilen.

`<!`

  Die Zeichenkette `<!` dient hier als Indikator, dass es sich bei diesem Ausdruck um eine SGML-Deklaration handelt und diese Zeile den Dokumententyp festlegt.

`DOCTYPE`

  Zeigt an, dass dies die SGML-Deklaration für den Dokumententyp ist.

`html`

  Nennt das erste Element, das im Dokument auftaucht.

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

  Nennt den Formalen Öffentlichen Bezeichner [5] der DTD des Dokuments. Diese Information wird von SGML-Parsern ausgewertet, um die von dem Dokument referenzierte DTD zu bestimmen.

  Das Schlüsselwort `PUBLIC` gehört nicht zum öffentlichen Bezeichner, sondern legt fest, wie ein SGML-Parser die DTD finden kann. Alternative Wege eine DTD zu referenzieren werden später gezeigt.

`>`

  Schließt den mit `<!` begonnenen Ausdruck ab.

### 3.3.1. Formale Öffentliche Bezeichner

> Anmerkung: Dieser Abschnitt braucht nicht unbedingt zu gelesen zu werden. Dennoch ist es empfehlenswert, da er nützliche Hintergrundinformationen enthält, die hilfreich sein können, falls der SGML-Prozessor die genutzte DTD nicht finden kann.

Jeder öffentliche Bezeichner muss eine bestimmte Syntax haben, die wie folgt lautet:

    "Besitzer//Schlüsselwort Beschreibung//Sprache"

`Besitzer`

  Nennt den Besitzer des öffentlichen Bezeichners.

  Falls diese Zeichenkette mit ISO beginnt, gehört der Bezeichner dem ISO-Kommitee. Der Bezeichner `"ISO 8879:1986//ENTITIES Greek Symbols//EN"` nennt ISO 8879:1986 als den Besitzer des Satzes von Entitäten für griechische Zeichen. ISO 8879:1986 ist die ISO-Bezeichnung für den SGML-Standard.

  Beginnt die Zeichenkette nicht mit ISO, sieht sie entweder so `-//`Besitzer`` oder so `+//`Besitzer`` aus. Beide Varianten unterscheiden sich also nur durch das anfängliche `+` bzw. `-`.

  Sofern am Anfang ein `-` steht, ist der Bezeichner nicht öffentlich registriert, steht hingegen ein `+` am Anfang, ist er registriert.

  Im ISO-Standard ISO 9070:1991 wurde festgelegt, wie registrierte Namen erzeugt werden können. Unter anderem können sie von den Bezeichnungen von ISO-Publikationen, von ISBN-Nummern oder einer Organisationsbezeichnungen entsprechend ISO 6523 abgeleitet werden. Anträge für neue offiziell registrierte Bezeichner werden vom ISO-Kommitee an das American National Standards Institute (ANSI) weitergeleitet.

  Da das FreeBSD-Projekt seine Bezeichner nicht hat registrieren lassen, ist der Besitzer `-//FreeBSD`. Unter anderem kann man daran auch sehen, dass das W3C sich nicht hat registrieren lassen.

`Schlüsselwort`

  Es gibt verschiedene Schlüsselwörter mit denen man die Art der gegebenen Informationen beschreiben kann. Einige der üblichsten sind `DTD`, `ELEMENT`, `ENTITIES` und `TEXT`. `DTD` wird nur für Dateien mit DTDs verwandt, `ELEMENT` findet für Dateien mit Fragmenten von DTDs Verwendung, die nur Deklarationen für Entitäten und Elemente enthalten. `TEXT` wird für SGML-Inhalte (Texte und Tags) verwendet.

`Beschreibung`

  Eine frei wählbare Beschreibung des Inhalts der referenzierten Datei. Möglich sind hier Versionsnummern oder ein kurzer und sinnvoller Text, der innerhalb der SGML-Welt eindeutig ist.

`Sprache`

  Ein ISO-Code aus zwei Buchstaben, der die für die Datei verwendete Sprache nennt. `EN` steht hier für Englisch, `DE` für Deutsch.

#### 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/sgml/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/sgml/docbook/4.1/catalog`

- `/usr/local/share/sgml/html/catalog`

- `/usr/local/share/sgml/iso8879/catalog`

- `/usr/local/share/sgml/jade/catalog`

Allerdings sollte das schon geschehen sein.

### 3.3.2. Alternativen zu Formalen Öffentlichen Bezeichnern

Anstatt mit einem Bezeichner die zum Dokument gehörende DTD zu referenzieren, kann auch explizit auf die Datei der DTD verwiesen werden.

Die Syntax des DOCTYPE-Deklaration ist in diesem Falle anders:

    <!DOCTYPE html SYSTEM "/pfad/zur/dokumenten.dtd">

Das Schlüsselwort `SYSTEM` legt fest, dass ein SGML-Prozessor die DTD auf systemspezifische Art und Weise bestimmen soll. Meistens, aber nicht immer, wird so auf eine Datei im Dateisystem verwiesen.

Allerdings sollte man öffentliche Bezeichner aus Gründen der Portabilität bevorzugen, da man so nicht eine Kopie der DTD mit dem Dokument selber verteilen muss, beziehungsweise da man, wenn man mit `SYSTEM` arbeitet, nicht davon ausgehen kann, dass die benötigte DTD auf anderen Systemen genau unter dem gleichen Pfad verfügbar ist.

## 3.4. Die Rückkehr zu SGML

An einer früheren Stelle wurde erwähnt, dass man SGML nur benötigt, falls man selbst eine DTD entwickeln möchte. Genaugenommen ist das nicht 100%ig richtig. Einige Teile der SGML-Syntax können auch in normalen Dokumenten verwendet werden, falls dies gewünscht oder notwendig ist.

In diesem Falle muss dafür Sorge getragen werden, dass ein SGML-Prozessor feststellen kann, dass ein bestimmter Abschnitt des Inhalts SGML ist, das er verarbeiteten muss.

Solche SGML-Abschnitte werden mittels `<! ... >` in Dokumenten besonders gekennzeichnet. Alles, was sich zwischen diesen Begrenzungen befindet, ist SGML, wie es auch in DTDs gefunden werden kann.

Demnach ist die DOCTYPE-Deklaration ein gutes Beispiel für SGML, das in Dokumenten verwendet werden muss...

## 3.5. Kommentare

Kommentare sind SGML-Konstrukte, die normalerweise nur in DTDs gültig sind. Dennoch ist es, wie in Abschnitt 3.4 gezeigt, möglich Fragmente mit SGML-Syntax in Dokumenten zu verwenden.

Zum Abgrenzen von SGML-Kommentaren wird ein doppelter Bindestrich `--` verwendet. Mit seinem ersten Auftreten öffnet er einen Kommentar, mit seinem zweiten schließt er ihn wieder.

Beispiel 3-8. Beispiele für Kommentare in SGML

    <!-- Testkommentar -->

    <!-- Text innerhalb eines Kommentars -->

    <!-- Ein anderer Kommentar    -->

    <!-- So können mehrzeilige Kommentare
         genutzt werden -->

    <!-- Eine andere Möglichkeit für --
      -- mehrzeilige Kommentare.     -->

Hat man früher schon Erfahrungen mit HTML gesammelt, wird man vielleicht andere Regeln für den Gebrauch von Kommentaren kennengelernt haben. Beispielsweise wird oft angenommen, dass Kommentare mit `<!--` begonnen und nur mit `-->` beendet werden.

Dies ist nicht der Fall. Viele Webbrowser haben fehlerhafte HTML-Parser, die dies akzeptieren. Die SGML-Parser, die vom FDP verwendet werden, halten sich strenger an die SGML-Spezifikation und verwerfen Dokumente mit solchen Fehlern.

Beispiel 3-9. Fehlerhafte SGML-Kommentare

    <!-- Innerhalb eines Kommentars --

         DIES IST NICHT TEIL EINES KOMMENTARS

      -- Wieder innerhalb eines Kommentars -->

SGML-Parser würden die mittlere Zeile wie folgt interpretieren:

    <!DIES IST NICHT TEIL EINES KOMMENTARS>

Da es sich hierbei nicht um gültiges SGML handelt, kann diese Zeile zur verwirrenden Fehlermeldungen führen.

    <!--------------- Eine wirklich schlechte Idee  --------------->

Wie das Beispiel zeigt, sollten solche Kommentare tunlichst vermieden werden.

    <!--===================================================-->

Ein solcher Kommentar ist (ein wenig) besser, kann aber jemanden, der mit SGML noch nicht so vertraut ist, verwirren.

### 3.5.1. Fingerübungen...

1. Zur Übung können Sie einige Kommentare in die Datei `beispiel.sgml` einfügen und überprüfen, ob die Datei nun noch erfolgreich von `onsgmls` validiert werden kann.

2. Zu Testzwecken sollten Sie auch noch ein paar fehlerhafte Kommentare hinzufügen und sich die resultierenden Fehlermeldungen von `onsgmls` ansehen.

## 3.6. Entitäten

Entitäten stellen einen Mechanismus dar, mit dem einzelnen Dokumententeilen ein Name zugewiesen werden kann. Findet ein SGML-Parser während des Parsens eine Entität, ersetzt er diese durch den ihr zugewiesenen Inhalt.

Dadurch steht eine einfache Möglichkeit zur Verfügung, mit der variabler Inhalt in SGML-Dokumenten eingebunden werden kann. Zusätzlich sind Entitäten der einzige Weg, über den eine Datei in eine andere Datei mit SGML-Mitteln eingebunden werden kann.

Es werden zwei Arten von Entitäten unterschieden: Allgemeine Entitäten und Parameterentitäten.

### 3.6.1. Allgemeine Entitäten

Allgemeine Entitäten können nur in Dokumenten benutzt werden. Sie können zwar im SGML-Kontext definiert aber dort nicht benutzt werden. Vergleichen Sie dies mit Im Parameterentitäten.

Jede allgemeine Entität hat einen Namen, über den sie angesprochen werden kann, um den von ihr referenzierten Inhalt in ein Dokument einzubinden. Dafür muss an der betreffenden Stelle der Namen der Entität per `&`entitaetenname`;` einfügt werden. Eine Entität `current.version` könnte beispielsweise durch die aktuelle Versionsnummer eines Programms ersetzt werden. Man könnte also schreiben:

    <para>Die aktuelle Version des
      Programms ist &current.version;.</para>

Wenn sich die Versionsnummer ändert, muss nur die Entität angepasst und anschließend das Dokument neu erzeugt werden.

Eine weitere Einsatzmöglichkeit für Allgemeine Entitäten ist das Einbinden von Zeichen, die auf andere Weise nicht in ein SGML-Dokument eingefügt werden könnten. Ein Beispiel für solche Zeichen sind `<` und `&`, die normalerweise nicht direkt in SGML-Dokumenten erlaubt sind. Stößt ein SGML-Parser bei seiner Arbeit auf das Symbol `<`, nimmt er an, dass der Anfang eines Start- oder Endtags gefunden wurde. Bei einem `&` wird er annehmen, den Anfang einer Entität gefunden zu haben.

Wenn eines der beiden Zeichen benötigt wird, werden daher die allgemeinen Entitäten `&lt;` und `&amp;` verwendet.

Allgemeine Entitäten können nur in einem SGML-Kontext definiert werden. Üblich ist es, dies direkt nach der DOCTYPE-Deklaration zu tun:

Beispiel 3-10. Allgemeine Entitäten festlegen

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!ENTITY current.version    "3.0-RELEASE">
    <!ENTITY last.version       "2.2.7-RELEASE">
    ]>

Wichtig ist an dieser Stelle, dass die DOCTYPE-Deklaration durch eine eckige Klammer am Ende der ersten Zeile erweitert wurde. Die beiden Entitäten selber werden in den folgenden zwei Zeilen definiert, bevor in der letzten Zeile die eckige Klammer und die DOCTYPE-Deklaration wieder geschlossen werden.

Die eckigen Klammern sind notwendig um festzulegen, dass man die über DOCTYPE genannte DTD erweitern möchte.

### 3.6.2. Parameterentitäten

Genau wie Allgemeine Entitäten werden Parameterentitäten eingesetzt um wiederverwendbare Inhaltsteile mit Namen zu versehen. Im Gegensatz zu Allgemeinen Entitäten können sie aber nur innerhalb eines SGML-Kontextes genutzt werden.

Die Definition von Parameterentitäten erfolgt ähnlich zu der Allgemeiner Entitäten. Sie werden lediglich mit `%`entitaetenname`;` anstelle von `&`entitaetenname`;` referenziert[6]. Wichtig ist, dass das `%`-Zeichen zwischen `ENTITY` und dem Entitätennamen ein Teil der Definition ist.

Beispiel 3-11. Parameterentitäten festlegen

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!ENTITY % param.etwas "etwas">
    <!ENTITY % param.text "Text">
    <!ENTITY % param.neu  "%param.etwas mehr %param.text">

    <!-- %param.neu ist jetzt "etwas mehr Text" -->
    ]>

### 3.6.3. Fingerübungen...

1. Fügen Sie in `beispiel.sgml` eine Allgemeine Entität ein.

       <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
       <!ENTITY version "1.1">
       ]>

       <html>
         <head>
           <title>Eine HTML-Beispieldatei</title>
         </head>

         <body>
           <p>Das ist ein Absatz mit etwas Text.</p>

           <p>Das ist ein Absatz mit anderem Text.</p>

           <p align="right">Dieser Absatz wird rechtsbündig
             ausgerichtet.</p>

           <p>Die aktuelle Version ist: &version;</p>
         </body>
       </html>

2. Validieren Sie diese Datei mit `onsgmls`

3. Öffnen Sie nun `beispiel.sgml` mit Ihrem Webbrowser. Es kann notwendig sein, dass Sie die Datei vorher in `beispiel.html` umbenennen müssen, damit die Datei auch als HTML-Dokument erkannt wird.

   Nur wenn Sie einen sehr modernen Browser haben, werden Sie sehen können, dass `&version;` durch die Versionsnummer ersetzt wurde. Leider haben die meisten Webbrowser sehr einfache SGML-Parser, die nicht richtig mit SGML umgehen können[7].

4. Die Lösung hierfür ist, das Dokument zu normalisieren. Zu diesem Zweck liest ein Normer das Dokument ein und gibt anschließend semantisch gleichwertiges SGML wieder aus, dass auf verschiedene Arten transformiert worden sein kann. Eine dieser möglichen Transformationen ist das Ersetzen der Referenzen auf Entitäten mit dem von ihnen präsentierten Inhalt.

   Versuchen Sie, die Beispieldatei mittels `osgmlnorm` zu normalisieren:

       % osgmlnorm beispiel.sgml > beispiel.html

   Anschließend sollten Sie eine normalisierte Version, dass heißt eine, bei der die Entitäten gegen ihren Inhalt ersetzt wurden, in der Datei `beispiel.html` finden. Diese Datei können Sie sich nun mit Ihrem Browser ansehen.

5. Wenn Sie sich die Ausgaben von `osgmlnorm` ansehen, werden Sie feststellen, dass die DOCTYPE-Deklaration am Anfang der Datei nicht mehr enthalten ist. Möchten Sie die Deklaration behalten, muss `osgmlnorm` mit der Option `-d` aufrufen werden:

       % osgmlnorm -d beispiel.sgml > beispiel.html

## 3.7. Dateien mit Entitäten einbinden

Sowohl Allgemeine als auch Parameterentitäten sind nützliche Helfer, wenn es darum geht, eine Datei in eine andere einzubinden.

### 3.7.1. Dateien mit Allgemeinen Entitäten einbinden

Angenommen man hat ein Buch geschrieben, dessen Inhalt auf mehrere Dateien aufgeteilt und mittels SGML ausgezeichnet. Jedes Kapitel wurde dazu in einer eigenen Datei (`kapitel1.sgml`, `kapitel2.sgml` usw.) abgelegt und über eine Datei `buch.sgml` sollen alle physischen Dateien wieder mit der Hilfe von Entitäten zu einem logischen Dokument zusammengeführt werden.

Damit der Inhalt der Dateien mit Entitäten eingebunden werden kann, muss die Deklaration der Entitäten das Schlüsselwort `SYSTEM` enthalten. SGML-Parser werden so angewiesen, den Inhalt der referenzierten Datei als Wert für die jeweilige Entität zu nehmen.

Beispiel 3-12. Dateien mit Allgemeinen Entitäten einbinden

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!ENTITY kapitel.1 SYSTEM "kapitel1.sgml">
    <!ENTITY kapitel.2 SYSTEM "kapitel2.sgml">
    <!ENTITY kapitel.3 SYSTEM "kapitel3.sgml">
    <!-- Und so weiter... -->
    ]>

    <html>
      <!-- Jetzt werden die Kapitel über die Entitäten eingebunden -->

      &kapitel.1;
      &kapitel.2;
      &kapitel.3;
    </html>

> Warnung: Wenn man Allgemeine Entitäten benutzt, um andere Dateien einzubinden, dürfen diese Dateien (`kapitel1.sgml`, `kapitel2.sgml`, ...) keine eigene DOCTYPE-Deklaration haben.

### 3.7.2. Dateien mit Parameterentitäten einbinden

Wie bereits festgestellt, können Parameterentitäten nur innerhalb eines SGML-Kontexts genutzt werden. Warum möchte man aber Dateien innerhalb eines SGML-Kontexts einbinden? Der Vorteil liegt in der Möglichkeit, die Deklaration von Entitäten in eine andere Datei auslagern zu können, wodurch diese leichter wiederverwendbar sind.

Angenommen das Buch aus dem vorherigen Kapitel besteht aus sehr vielen Kapiteln und diese sollen auch in einem anderen Buch, aber in einer anderen Reihenfolge, verwendet werden. Eine Möglichkeit wäre es, die dafür notwendigen Entitäten am Anfang jedes Buches einzeln festzulegen - was allerdings mit der Zeit unhandlich und fehlerträchtig wird.

Alternativ bietet sich dazu an, die Deklarationen in eine separate Datei auszulagern und deren Inhalt anschließend in beide Bücher über Parameterentitäten einzubinden.

Beispiel 3-13. Dateien mit Parameterentitäten einbinden

Zuerst werden die Entitäten in einer separaten Datei namens `kapitel.ent` deklariert. `kapitel.ent` enthält für dieses Beispiel die folgenden Zeilen:

    <!ENTITY kapitel.1 SYSTEM "kapitel1.sgml">
    <!ENTITY kapitel.2 SYSTEM "kapitel2.sgml">
    <!ENTITY kapitel.3 SYSTEM "kapitel3.sgml">

Im zweiten Schritt fügt man in beide Bücher eine Parameterentität ein, die den Inhalt von `kapitel.ent` referenziert, und lädt über diese dann die Deklarationen. Anschließend können die so geladenen Entitäten wie gewohnt genutzt werden.

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!-- Definieren einer Parameterentität um die Allgemeinen Entitäten für -->
    <!-- die Kapitel laden zu können                                        -->
    <!ENTITY % kapitel SYSTEM "kapitel.ent">

    <!-- Nun wird der Inhalt der referenzierten Datei geladen -->
    %kapitel;
    ]>

    <html>
      &kapitel.1;
      &kapitel.2;
      &kapitel.3;
    </html>

### 3.7.3. Fingerübungen...

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

1. Legen Sie drei Dateien (`absatz1.sgml`, `absatz2.sgml` und `absatz3.sgml`) mit jeweils einer Zeile wie

       <p>Erster Absatz.</p>

   an.

2. Ändern Sie `beispiel.sgml` so ab, dass sie wie folgt aussieht:

       <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
       <!ENTITY version "1.1">
       <!ENTITY absatz1 SYSTEM "absatz1.sgml">
       <!ENTITY absatz2 SYSTEM "absatz2.sgml">
       <!ENTITY absatz3 SYSTEM "absatz3.sgml">
       ]>

       <html>
         <head>
           <title>Eine HTML-Beispieldatei</title>
         </head>

         <body>
           <p>Die aktuelle Version dieses Dokuments ist &version;</p>

           &absatz1;
           &absatz2;
           &absatz3;
         </body>
       </html>

3. Erzeugen Sie nun die Datei `beispiel.html`, indem Sie `beispiel.sgml` normalisieren:

       % osgmlnorm -d beispiel.sgml > beispiel.html

4. Öffnen Sie `beispiel.html` nun mit einem Webbrowser und vergewissern Sie sich, dass der Inhalt der Dateien `absatz`N`.sgml` in `beispiel.html` übernommen wurde.

#### 3.7.3.2. Binden Sie Dateien mit Parameterentitäten ein

> Anmerkung: Hierfür müssen Sie die vorherige Fingerübung gemacht haben.

1. Ändern Sie `beispiel.sgml` so ab, dass es wie folgt aussieht:

       <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
       <!ENTITY % entitaeten SYSTEM "entitaeten.sgml"> %entitaeten;
       ]>

       <html>
         <head>
           <title>Eine HTML-Beispieldatei</title>
         </head>

         <body>
           <p>Die aktuelle Version dieses Dokuments ist &version;</p>

           &absatz1;
           &absatz2;
           &absatz3;
         </body>
       </html>

2. Legen Sie eine weitere Datei `entitaeten.sgml` an, die folgenden Inhalt hat:

       <!ENTITY version "1.1">
       <!ENTITY absatz1 SYSTEM "absatz1.sgml">
       <!ENTITY absatz2 SYSTEM "absatz2.sgml">
       <!ENTITY absatz3 SYSTEM "absatz3.sgml">

3. Erzeugen Sie die Datei `beispiel.html`, indem Sie `beispiel.sgml` normalisieren:

       % osgmlnorm -d beispiel.sgml > beispiel.html

4. Öffnen Sie `beispiel.html` nun mit einem Webbrowser und vergewissern Sie sich, dass der Inhalt der Dateien `absatz`N`.sgml` in `beispiel.html` übernommen wurde.

## 3.8. Markierte Bereiche

SGML erlaubt es, dass bestimmte Dokumentabschnitte während der Verarbeitung besonders behandelt werden sollen. Diese Abschnitte werden als markierte Bereiche [8] bezeichnet.

Beispiel 3-14. Aufbau eines markierten Bereiches

    <![ SCHLÜSSELWORT [
      Inhalt des markierten Bereiches
    ]]>

Da es sich bei markierten Bereichen um SGML-Konstrukte handelt, werden sie mit `<!` eingeleitet. Der eigentliche Anfang des markierten Bereiches wird von der folgenden eckigen Klammer bestimmt. Das darauf folgende `SCHLÜSSELWORT` legt fest, wie der markierte Inhalt durch einen SGML-Prozessor während der Verarbeitung behandelt werden soll. Der markierte Inhalt selbst beginnt erst nach der zweiten eckigen Klammer und erstreckt sich bis zu den zwei schließenden eckigen Klammern am Ende des Bereiches. Mit Hilfe des `>` Zeichens wird der mit `<!` begonnene SGML-Kontext wieder verlassen.

### 3.8.1. Schlüsselworte für markierte Bereiche

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

> Anmerkung: Bei der Verwendung von `CDATA` und `RCDATA` als Inhaltsmodell für SGML-Beispiele, wie sie in diesem Dokument enthalten sind, muss bedacht werden, dass der Inhalt eines `CDATA`-Bereiches nicht validiert wird. dass das SGML in diesen Bereichen gültig ist, muss auf andere Weise sichergestellt werden. Denkbar ist beispielsweise, es in einem separaten Dokument zu erstellen, dort zu prüfen und erst dann in das eigentliche Dokument einzufügen.

Beispiel 3-15. CDATA als Inhaltsmodell für markierte Bereiche

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

Liest man die Quellen dieser Fibel, wird man feststellen, dass diese Technik durchgängig angewandt wurde.

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

Beispiel 3-16. Anwendung von `INCLUDE` und `IGNORE` in markierten Abschnitten

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

Beispiel 3-17. Kontrolle von markierten Bereichen über Parameterentitäten

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

Bei der Produktion der gedruckten Variante muss der Wert der Entität geändert werden.

    <!ENTITY % digitale.kopie "IGNORE">

Bei der Verarbeitung wird als Schlüsselwort in beiden Fällen der von `%digitale.kopie` repräsentierte Wert verwendet. Im ersten Fall wird der Inhalt des markierten Bereichs mitverarbeitet, im zweiten Fall nicht.

### 3.8.2. Fingerübung...

1. Legen Sie eine neue Datei `abschnitt.sgml` an, die folgenden Inhalt hat:

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

       <html>
         <head>
           <title>Ein Beispiel mit markierten Abschnitten</title>
         </head>

         <body>
           <p>Dieser Absatz <![ CDATA [beinhaltet viele <
             Zeichen (< < < < <). Weshalb es einfacher ist,
             ihn als CDATA Bereich auszuweisen. ]]></p>

           <![ IGNORE [
           <p>Dieser Absatz wird NICHT in der Ausgabe enthalten sein.</p>
           ]]>

           <![ %text.ausgabe [
            <p>Dieser Absatz wird in Abhängigkeit von %text.ausgabe
              mitausgegeben.</p>
           ]]>
         </body>
       </html>

2. Normalisieren Sie den Inhalt dieser Datei mit Hilfe von `osgmlnorm` und sehen Sie sich das Ergebnis an. Achten Sie dabei darauf, welche Absätze enthalten beziehungsweise nicht enthalten sind und was aus den `CDATA`-Bereichen geworden ist.

3. Ändern Sie die Definition von `text.ausgabe` so, dass es den Wert `IGNORE` zugewiesen bekommt. Verarbeiten Sie dann die Datei erneut mit `osgmlnorm` und vergleichen die Ausgabe mit der vom ersten `osgmlnorm` Lauf.

## 3.9. Schlußbemerkung

Aus Platzgründen, und um der Verständlichkeit Willen, wurden viele Gesichtspunkte nicht in aller Tiefe beziehungsweise gar nicht besprochen. Trotzdem sollte in den bisherigen Kapiteln genügend Wissen über SGML vermittelt worden sein, um den Aufbau der Dokumentation des FDPs zu verstehen.

# 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[11].

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

        <URL:http://people.FreeBSD.org/~nik/primer/index.html>

      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>` [12]. 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>

## 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 [13]. 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 Die Würde des Menschen ist unantastbar. Sie zu achten und zu schützen ist Verpflichtung aller staatlichen Gewalten. 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. 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.[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.

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

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[16]. 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[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/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.

# Kapitel 5. Stylesheets

Übersetzt von Johann Kois.

SGML legt nicht fest, wie ein Dokument am Monitor oder auf einem Ausdruck dargestellt werden soll. Für diese Aufgabe wurden spezielle Sprachen entwickelt, die Formatvorlagen (die sogenannten Stylesheets) für die Darstellung der Inhalte definieren. Zu diesen Sprachen gehören beispielsweise DynaText, Panorama, SPICE, JSSS, FOSI, CSS, DSSSL und andere mehr.

DocBook verwendet in DSSSL geschriebene Stylesheets. HTML verwendet hingegen in CSS geschriebene Stylesheets.

## 5.1. DSSSL

Das Documentation Project verwendet eine anpasste Version der von Norm Walsh entwickelten modularen DocBook-Stylesheets, die über den Port `textproc/dsssl-docbook-modular` installiert werden können.

Die FreeBSD-Modifikationen sind hingegen nicht in der Ports-Sammlung enthalten, sondern befinden sich im Quellcode-Repository des Documentation Projects in der Datei `doc/share/sgml/freebsd.dsl`. Diese Datei ist umfassend kommentiert und mit Beispielen versehen. Dadurch können Sie einfach nachvollziehen, wie die ursprünglichen Stylesheets vom FreeBSD Documentation Project angepasst wurden.

## 5.2. CSS

Cascading Stylesheets (CSS) erlauben es, Elementen eines HTML-Dokuments Formatangaben (wie Schriftart, Größe, Schriftfarbe und andere mehr) zuzuweisen, ohne das HTML-Dokument mit diesen Informationen zu überfrachten.

### 5.2.1. Die DocBook-Dokumente

The FreeBSD DSSSL-Stylesheets enthalten eine Referenz auf ein Stylesheet namens `docbook.css`, das sich im gleichen Verzeichnis wie die HTML-Dateien befindet. Diese projektweite CSS-Datei wird automatisch von `doc/share/misc/docbook.css` kopiert und installiert, wenn DocBook-Dokumente nach HTML konvertiert werden.

# Kapitel 6. Verzeichnisstruktur unter `doc/`

Übersetzt von Johann Kois.

Der `doc/`-Baum ist auf eine besondere Weise organisiert. Dies gilt analog für die Dokumente, aus denen der FDP besteht. Das Ziel dieser Organisation ist es, das Hinzufügen neuer Dokumente zu erleichtern, sowie

1. die automatische Konvertierung der Dokumente in andere Formate einfach zu gestalten,

2. die Konsistenz zwischen den verschiedenen auf diese Weise organisierten Dokumenten sicherzustellen, was die parallele Bearbeitung verschiedener Dokumente vereinfacht, sowie

3. die Entscheidung, wo neue Dokumente innerhalb des Baumes platziert werden sollen, zu erleichtern.

Zusätzlich wird dadurch dem Umstand Rechnung getragen, dass die Dokumentation in verschiedenen Sprachen und Kodierungen vorhanden sein kann. Es ist von großer Bedeutung, dass die Struktur des Dokumentationsbaumes dabei dennoch einheitlich bleibt.

## 6.1. `doc/` als höchste Ebene

Unterhalb von `doc/` existieren zwei Arten von Verzeichnissen, die jeweils über spezifische Dateinamen und eine spezifische Bedeutung verfügen.

Verzeichnis: `share/`

Bedeutung: Enthält Dateien, die für alle Sprachen und Kodierungen der Dokumentation gültig sind. Es enthält weitere Unterverzeichnisse, um diese Informationen zu kategorisieren. So enthält `share/mk` beispielsweise die Dateien, die die make(1)-Infrastruktur bilden, während sich die für die SMGL-Unterstützung nötigen Dateien (darunter die FreeBSD DocBook DTD) unter `share/sgml` befinden.

Verzeichnis: ``Sprache`.`Kodierung`/`

Bedeutung: Für jede verfügbare Sprache und Kodierung existiert ein eigenes Unterverzeichnis. Beispiele dafür sind `en_US.ISO8859-1/` oder `zh_TW.Big5/`. Zwar sind diese Verzeichnisnamen nicht gerade kurz, durch die vollständige Angabe von Sprache und Kodierung werden aber Probleme bei einer eventuellen Erweiterung der Dokumentation (etwa um eine zusätzliche Kodierung für eine bereits vorhandene Sprache) vermieden. Auch eine eventuelle Konvertierung der Dokumentation nach Unicode ist dadurch problemlos möglich.

## 6.2. Die Verzeichnisse ``Sprache`.`Kodierung`/`

Diese Verzeichnisse enthalten die eigentliche Dokumentation. Auf dieser Ebene erfolgt eine Unterteilung in drei Kategorien, die durch entsprechende Verzeichnisnamen gekennzeichnet werden.

Verzeichnis: `articles`

Inhalt: DocBook-formatierte Artikel (`<article>`) oder ähnliche Dokumente. Meist relativ kurz und in Abschnitte aufgeteilt. Artikel sind in der Regel als ein einziges, großes HTML-Dokument verfügbar.

Verzeichnis: `books`

Inhalt: DocBook-formatierte Bücher (`<book>`) oder ähnliche Dokumente. Umfangreiche Dokumente, die in Kapitel aufgeteilt werden. Sind in der Regel sowohl als eine einzige, große HTML-Datei (für Personen mit einer schnellen Internetanbindung oder für einen einfachen Druck über ein Browser) oder als eine Sammlung von vielen kleinen, miteinander verlinkten Dateien verfügbar.

Verzeichnis: `man`

Inhalt: Dient für Übersetzungen von Manualpages. Es enthält ein oder mehrere `man`n``-Verzeichnisse, je nachdem, welche Abschnitte der Manualpages bereits übersetzt wurden.

Nicht jedes ``Sprache`.`Kodierung``-Verzeichnis enthält all diese Unterverzeichnisse. Ob ein Verzeichnis vorhanden ist, hängt vielmehr davon ab, ob bereits ein entsprechender Teil der Dokumentation übersetzt wurde.

## 6.3. Dokumentenspezifische Informationen

Dieser Abschnitt enthält Informationen zu einigen vom FreeBSD Documentation Project (FDP) verwalteten Dokumenten.

### 6.3.1. Das Handbuch

`books/handbook/`

Das Handbuch wurde unter Verwendung der vom FreeBSD Project erweiterten DocBook-DTD geschrieben.

Das Handbuch ist als DocBook-`<book>` organisiert. Es besteht aus mehreren Teilen (`<part>`s), die wiederum mehrere Kapitel (`<chapter>`) enthalten können. Kapitel sind zusätzlich in Abschnitte (`<sect1>`) und Unterabschnitte (`<sect2>`, `<sect3>` und so weiter) unterteilt.

#### 6.3.1.1. Physikalische Organisation

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

> Anmerkung: Die Organisation des Handbuchs hat sich im Laufe der Zeit geändert, daher könnten die Informationen in diesem Abschnitt eventuell nicht mehr dem akutellen Stand entsprechen. Haben Sie Fragen zur Organisation des Handbuchs, so wenden Sie sich bitte an das FreeBSD documentation project.

##### 6.3.1.1.1. `Makefile`

Das `Makefile` definiert verschiedene Variablen zur Konvertierung der SGML-Quellen in andere Formate. Außerdem listet es die verschiedenen Dateien auf, aus denen das Handbuch gebaut wird. Zusätzlich wird die Standard-`doc.project.mk` inkludiert, die den für die Konvertierung in andere Formate notwendigen Code bereitstellt.

##### 6.3.1.1.2. `book.sgml`

Das Hauptdokument innerhalb des Handbuchs. Neben der DOCTYPE-Deklaration des Handbuchs werden hier auch die Elemente aufgelistet, die die Struktur des Handbuchs definieren.

`book.sgml` verwendet Parameterentitäten, um Dateien mit der Endung `.ent` zu laden. Diese Dateien definieren die allgemeinen Entitäten, die innerhalb des Handbuchs verwendet werden.

##### 6.3.1.1.3. ``Verzeichnis`/chapter.sgml`

Jedes Kapitel des Handbuchs wird in einer `chapter.sgml` genannten Datei gespeichert. Jedes Verzeichnis erhält den Namen des `id`-Attributs des `<chapter>`-Elements.

Enthält eine Kapiteldatei beispielsweise die Einträge

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

so handelt es sich um die Datei `chapter.sgml` im Verzeichnis `kernelconfig`. Im Allgemeinen enthält diese Datei das komplette Kapitel.

Wird die HTML-Version des Handbuchs gebaut, entsteht dadurch die HTML-Datei `kernelconfig.html`. Der Grund dafür ist allerdings der Wert des `id`-Attributs, und nicht der Name des Verzeichnisses.

In früheren Versionen des Handbuchs wurden all diese Dateien im gleichen Verzeichnis wie die Datei `book.sgml` gespeichert und nach dem Wert des `id`-Attributs der `<chapter>`-Elemente benannt. Durch die Verwendung von eigenen Verzeichnissen für die verschiedenen Kapitel wurde das Handbuch für künftige Erweiterungen vorbereitet. Beispielsweise wurde es dadurch möglich, Bilder in die einzelnen Kapitel aufzunehmen. Die Bilder für das Handbuch werden zentral im Verzeichnis `share/images/books/handbook` gespeichert. Existiert eine lokalisierte Version eines Bildes, wird diese hingegen gemeinsam mit dem SGML-Quellcode im gleichen Verzeichnis gespeichert. Ein Vorteil dieser Methode ist beispielsweise die Vermeidung von Namenskollisionen. Außerdem ist es übersichtlicher, mit mehreren Verzeichnissen zu arbeiten, die jeweils nur einige Dateien enthalten, als mit einem einzigen Verzeichnis, das eine Vielzahl von Dateien enthält.

Durch dieses Vorgehen entstanden viele Verzeichnisse, die jeweils eine `chapter.sgml` enhalten, beispielsweise `basics/chapter.sgml`, `introduction/chapter.sgml` oder `printing/chapter.sgml`.

> Wichtig: Im Normalfall sollte ein Umstrukturierung des Handbuchs nicht dazu führen, dass dafür Dateien umbenannt werden müssen (es sei denn, einzelne Kapitel werden neu aufgenommen oder entfernt). Kapitel und Verzeichnisse sollten daher nicht nach ihrer Reihenfolge innerhalb des Handbuchs benannt werden, da sich diese Reihenfolge bei einer Umstrukturierung des Handbuchs ändern könnte.

Die Datei `chapter.sgml` ist keine komplette SGML-Datei, da unter anderem die Zeilen mit der DOCTYPE-Deklaration am Beginn der Datei nicht vorhanden sind.

Durch diesen Umstand ist es nicht möglich, einzelne Dateien direkt nach HTML, RTF, PS oder ein anderes Format zu konvertieren. Vielmehr muss dazu das komplette Handbuch neu gebaut werden.

# Kapitel 7. Die Erzeugung der Zieldokumente

Übersetzt von Johann Kois.

Dieses Kapitels erklärt detailliert, wie der Bau der Dokumentation organisiert ist und wie Sie diesen Prozess beeinflussen können.

Nachdem Sie dieses Kapitel gelesen haben, werden Sie:

- Wissen, wie Sie (unter Verwendung der im Kapitel SGML-Werkzeuge beschriebenen Tools) die FDP-Dokumentation selbst bauen können.

- In der Lage sein, sowohl die make-Anweisungen der für jedes Dokument benötigten `Makefile`s als auch die Anweisungen der projektweiten Vorgaben der Datei `doc.project.mk` zu lesen und zu verstehen.

- Den Bau der Dokumentation über make-Variablen und make-Target anpassen können.

## 7.1. Für den Bau der FreeBSD-Dokumentation benötigte Werkzeuge

Zusätzlich zu den im Kapitel SGML-Werkzeuge beschriebenen Werkzeugen benötigen Sie noch folgende Programme:

- Das wichtigste Werzeug zum Bau der Dokumentation ist make, genauer Berkeley Make.

- Der Bau von Paketen erfolgt unter FreeBSD mit pkg_create. Wenn Sie ein anderes Betriebssystem als FreeBSD einsetzen, müssen Sie entweder ohne Pakete auskommen oder den Quellcode selbst kompilieren.

- gzip dient zur Erstellung komprimierter Versionen der Dokumentation. Unterstützt werden sowohl bzip2- als auch zip-Archive. Wollen Sie Pakete der Dokumentation erstellen, benötigen Sie auch noch tar.

- Mit install installieren Sie in der Standardeinstellung die Dokumentation auf Ihrem System. Es gibt aber auch alternative Wege, die Dokumentation zu installieren.

## 7.2. Die Makefiles des Dokumentationsbaums verstehen

Innerhalb des FreeBSD Documentation Projects gibt es drei verschiedene Arten von `Makefile`s:

- Ein `Makefile` in einem Unterverzeichnis gibt Anweisungen an dessen Dateien und Unterverzeichnisse weiter.

- Ein Dokument-`Makefile` beschreibt das Dokument, das aus dem Inhalt des jeweiligen Verzeichnisses gebaut werden soll.

- Make-Includes sind der "Klebstoff", der für den Bau der Dokumentation erforderlich ist. In der Regel heissen diese Dokumente `doc.`xxx`.mk`.

### 7.2.1. Unterverzeichnis-Makefiles

Derartige `Makefile`s sind in der Regel wie folgt aufgebaut:

    SUBDIR =articles
    SUBDIR+=books

    COMPAT_SYMLINK = en

    DOC_PREFIX?= ${.CURDIR}/..
    .include "${DOC_PREFIX}/share/mk/doc.project.mk"

Die ersten vier nicht-leeren Zeilen definieren die make-Variablen `SUBDIR`, `COMPAT_SYMLINK`, und `DOC_PREFIX`.

Die erste `SUBDIR`-Anweisung weist (ebenso wie die `COMPAT_SYMLINK`-Anweisung) einer Variable einen Wert zu und überschreibt dabei deren ursprünglichen Wert.

Die zweite `SUBDIR`-Anweisung zeigt, wie man den aktuellen Wert einer Variable ergänzen kann. Nach der Ausführung dieser Anweisung hat die Variable `SUBDIR` den Wert `articles books`.

Die Anweisung `DOC_PREFIX` zweigt, wie man einer Variable einen Wert zuweist (vorausgesetzt, die Variable ist nicht bereits definiert). Eine derartige Anweisung ist beispielsweise sinnvoll, wenn sich `DOC_PREFIX` nicht dort befindet, wo es vom `Makefile` erwartet wird. Durch das Setzen dieser Variable kann der korrekte Wert an das Makefile übergeben werden.

Was heißt dies nun konkret? Mit den `SUBDIR`-Anweisungen legen Sie fest, welche Unterverzeichnisse beim Bau der Dokumentation eingeschlossen werden müssen.

`COMPAT_SYMLINK` wird zur Erstellung von symbolischen Links zwischen den jeweiligen Dokumentsprachen und deren offizieller Kodierung benötigt (so wird beispielsweise `doc/en` nach `en_US.ISO-8859-1` verlinkt).

`DOC_PREFIX` gibt den Pfad zum Wurzelverzeichnis des Quellcode-Baums des FreeBSD Documentation Projects an. Diese Vorgabe kann jederzeit durch einen eigenen Wert ersetzt werden. Bei `.CURDIR` handelt es sich um eine in make eingebaute Variable, die den Pfad des aktuellen Verzeichnisses enthält.

Die letzte Zeile bindet `doc.project.mk`, die zentrale, projektweite make-Datei des FreeBSD Documentation Projects, in den Bau ein. Diese Datei enthält den "Klebstoff", der die diversen Variablen in Anweisungen zum Bau der Dokumentation konvertiert.

### 7.2.2. Dokument-Makefiles

Diese `Makefile`s definieren diverse make-Variablen mit Vorgaben zum Bau der im Verzeichnis enthaltenen Dokumentation.

Dazu ein Beispiel:

    MAINTAINER=nik@FreeBSD.org

    DOC?= book

    FORMATS?= html-split html

    INSTALL_COMPRESSED?= gz
    INSTALL_ONLY_COMPRESSED?=

    # SGML content
    SRCS=  book.sgml

    DOC_PREFIX?= ${.CURDIR}/../../..

    .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"

Die Variable `MAINTAINER` ist von zentraler Bedeutung. Sie legt fest, wer für ein bestimmtes Dokument des FreeBSD Documentation Projects verantwortlich ist.

`DOC` (ohne die Erweiterung `.sgml`) ist der Name des Hauptdokuments des Verzeichnisses, in dem sich das Makefile befindet. Mit `SRCS`-Anweisungen geben Sie alle Dokumente an, aus denen das Dokument besteht. Zusätzlich binden Sie damit wichtige Dateien ein, deren Änderung einen erneuten Bau der Dokumentation erforderlich macht.

Mit `FORMATS` geben Sie an, in welchen Formaten die Dokumentation gebaut werden soll. `INSTALL_COMPRESSED` enthält die Standardvorgaben, die beim Bau komprimierter Pakte der Dokumentation verwendet werden sollen. Der Variable `INSTALL_ONLY_COMPRESS` (die in der Voreinstellung leer ist) wird nur dann ein Wert zugewiesen, wenn ausschließlich komprimierte Pakete der Dokumentation erstellt werden sollen.

> Anmerkung: Die Zuweisung von Werten an verschiedene Variablen wurde bereits im Abschnitt Unterverzeichnis-Makefiles behandelt.

Die Variable `DOC_PREFIX` und die verschiedenen Include-Anweisungen sollten Ihnen ebenfalls bereits vertraut sein.

## 7.3. Make-Includes des FreeBSD Documentation Projects

Diese Dateien lassen sich am besten verstehen, indem man sich deren Inhalt näher ansieht. Konkret handelt es sich dabei um folgende Dateien:

- `doc.project.mk` ist die Haupt-Include-Datei, die bei Bedarf alle folgenden Include-Dateien enthält.

- `doc.subdir.mk` sorgt dafür, dass alle benötigten Verzeichnisse (und Unterverzeichnisse) beim Bau der Dokumentation durchlaufen werden.

- `doc.install.mk` definiert Variablen, die die Installation der Dokumentation beeinflussen.

- `doc.docbook.mk` wird verwendet, wenn die Variable `DOCFORMAT` den Wert `docbook` hat und und die Variable `DOC` gesetzt ist.

### 7.3.1. doc.project.mk

Diese Datei hat folgenden Aufbau:

    DOCFORMAT?=	docbook
    MAINTAINER?=	doc@FreeBSD.org

    PREFIX?=	/usr/local
    PRI_LANG?=	en_US.ISO8859-1

    .if defined(DOC)
    .if ${DOCFORMAT} == "docbook"
    .include "doc.docbook.mk"
    .endif
    .endif

    .include "doc.subdir.mk"
    .include "doc.install.mk"

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

> Anmerkung: `PRI_LANG` beeinflusst in keinster Weise, welche Dokumente gebaut werden können oder sollen. Diese Variable wird lediglich dazu verwendet, häufig verwendete Dokumente in das Wurzelverzeichnis der installierten Dokumentation zu verlinken.

#### 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 `.endif`s schließen die zwei weiter oben definierten Bedingungen.

### 7.3.2. doc.subdir.mk

Den Inhalt dieser Datei hier zu beschreiben, würde zu weit führen. Sie sollten aber nach dem Lesen der vorangegangenen Abschnitte und der folgenden Ausführungen in der Lage sein, Inhalt und Aufgabe dieser Datei zu verstehen.

#### 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.2.1. Vorhandene Targets

- `install` und `package` arbeiten nacheinander alle Unterverzeichnisse ab und rufen dabei jeweils ihre realen Versionen (`realinstall` beziehungsweise `realpackage`) auf.

- `clean` entfernt alle Dateien, die beim Bau der Dokumentation erzeugt wurden (dies sowohl im aktuellen Verzeichnis als auch in allen Unterverzeichnissen). `cleandir` hat die gleiche Aufgabe, würde aber zusätzlich die Objekt-Verzeichnisse löschen (falls diese existieren).

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

# Kapitel 8. Die Webseite

Übersetzt von Johann Kois.

## 8.1. Vorbereitung

Sorgen Sie für genügend Plattenplatz (zwischen 200 und 500 MB). Der genaue Wert hängt davon ab, welche Methode Sie zum Bau der Webseiten verwenden. Dieser Platz wird von den SGML-Werkzeugen, den benötigten Teilen des CVS-Baums, für temporären Speicher zum Bau der Seiten sowie für die Installation der Webseiten benötigt.

> Anmerkung: Stellen Sie sicher, dass Ihre Dokumentationsports aktuell sind. Wenn Sie sich nicht sicher sind, entfernen Sie die alten Ports mit pkg_delete(1), bevor Sie die neue Version installieren. Derzeit wird unter anderem jade-1.2 vorausgesetzt. Haben Sie beispielsweise jade-1.1 installiert, deinstallieren Sie es mit:

>     # pkg_delete jade-1.1

Sie haben zwei Möglichkeiten, an die für den Bau der Webseiten nötigen Dateien zu gelangen:

- Sie können `csup` verwenden, um eine lokale Kopie der Dateien von einem CVSup-Server herunterzuladen. Dies ist die einfachste Methode, da Sie keine zusätzlichen Programme installieren müssen. Das im nächsten Abschnitt beschriebene `supfile` lädt jeweils die aktuellste Version der benötigten Dateien herunter. Diese Methode ist ausreichend, wenn Sie die Webseiten nur lokal bauen wollen, aber keine Veränderungen committen wollen.

- Alternativ verwenden Sie `cvsup` im cvs-Modus, um ein lokales CVS-Repository zu erzeugen und zu verwalten. Dazu müssen Sie zwar ein zusätzliches Programm (`net/cvsup-without-gui`) installieren, haben aber zusätzliche Möglichkeiten, etwa die Verwaltung verschiedener Revisionen der doc/www-Dateien und deren Historie. Außerdem erlaubt es diese Methode Ihnen, Veränderungen in das zentrale FreeBSD-CVS-Repository zu committen.

### 8.1.1. Die einfache Methode: `csup` verwenden

`csup` ist Teil des FreeBSD-Basissystems und wird inzwischen von den meisten Benutzern zur Aktualisierung der Ports-Sammlung verwendet. Das folgende `supfile` kann dazu verwendet werden, um die zum Bau der Webseiten benötigten Dateien auszuchecken:

    #
    # This file checks out all collections required to rebuild
    # the FreeBSD website
    #
    # Use the nearest CVSup mirror
    # listed at http://www.freebsd.org/doc/handbook/mirrors.html.

    *default host=cvsup10.FreeBSD.org
    *default base=/var/db
    *default prefix=/usr/build
    *default release=cvs tag=.
    *default delete use-rel-suffix
    *default compress

    # This will retrieve the entire doc branch of the FreeBSD repository.

    doc-all

    # This will retrieve the files required for the website

    www

    # This will retrieve some basic ports info required for the build

    ports-base

Ändern Sie den Eintrag `default host` in einen CVSup-Spiegelserver in Ihrer Nähe, bevor Sie mit dem Checkout beginnen. Außerdem sollten Sie den Eintrag `default prefix` ändern, wenn Sie die ausgecheckten Dateien an einem anderen Ort speichern wollen. Danach speichern Sie die Datei beispielsweise als ``doc-www-supfile`` ab und führen den folgenden Befehl aus:

    # csup -g -L2 doc-www-supfile

Nachdem dieser Befehl ausgeführt wurde, finden Sie drei neue Verzeichnisse, `doc/`, `www/` sowie `ports/` im Verzeichnis, das Sie durch den Eintrag `default prefix` (in unserem Beispiel ``/usr/build``) festgelegt haben. Wir werden das gleiche Verzeichnis für den Bau der Webseiten verwenden, achten Sie daher unbedingt darauf, dass Sie über genügend Plattenplatz auf dieser Partition verfügen.

Das ist alles. Sie können nun mit dem Bau der Webseiten beginnen.

### 8.1.2. Die flexible Methode: Ein lokales `doc/www`-CVS-Repository verwenden

Diese Methode bietet Ihnen (wie bereits erwähnt), mehr Flexibilität, Sie müssen aber den Port oder das Paket `net/cvsup-without-gui` installieren.

> Anmerkung: Um `net/cvsup-without-gui` über die Ports-Sammlung zu installieren, muss zusätzlich der Port `lang/ezm3` (ein Modula 3-Compiler) installiert werden. Die Installation dieses Ports ist sehr zeitintensiv, daher ist es in der Regel am einfachsten, CVSup als Paket (Package) zu installieren.

CVSup besitzt einen speziellen cvs-Modus, mit dem Sie ,v-Dateien (aus denen ein CVS-Repository besteht) auschecken können. Dies ist mit csup derzeit noch nicht möglich. Weiterführende Informationen zu CVSup finden Sie im Abschnitt Synchronisation der Quellen des FreeBSD-Handbuchs.

Das `supfile` im folgenden Beispiel checkt alle cvs-Sammlungen aus, die Sie für den Bau der Webseiten benötigen und speichert Sie in einem lokalen CVS-Repository:

    #
    # This file will create a local CVS repository
    # with the collections required for a complete
    # FreeBSD website rebuild. It should be used with
    # cvsup *only* (csup will not work)

    *default host=cvsup10.FreeBSD.org
    *default base=/var/db
    *default prefix=/usr/dcvs
    *default release=cvs
    *default delete use-rel-suffix
    *default compress

    # The following collections are needed
    # for the website build

    ports-base
    doc-all
    www

    # These collections are needed
    # for CVS functionality

    cvsroot-common
    cvsroot-ports
    cvsroot-doc

Ändern Sie den Eintrag `default host` in einen CVSup-Spiegelserver in Ihrer Nähe, bevor Sie mit dem Checkout beginnen. Außerdem sollten Sie den Eintrag `default prefix` ändern, wenn Sie die ausgecheckten Dateien an einem anderen Ort speichern wollen. Danach speichern Sie die Datei beispielsweise als ``doc-www-cvsfile`` ab und führen den folgenden Befehl aus:

    # cvsup -g -L2 doc-www-cvsfile

Zusätzlich sollten Sie die Umgebungsvariable `CVSROOT` in den Startdateien Ihrer Shell setzen. Dazu nehmen Sie beispielsweise den folgenden Eintrag in die Datei `~/.cshrc` auf (wenn Sie die csh einsetzen):

    setenv CVSROOT /usr/dcvs

Wenn Sie diese Variable gesetzt haben, können Sie die Option `-d` (siehe weiter unten) weglassen, wenn Sie `cvs`-Operationen im Repository ausführen:

Derzeit benötigen Sie für ein Repository, das nur die zum Bau der Webseiten nötigen Dateien enthält, mehr als 400 MB freien Plattenplatz. Der Bau der Webseiten erfordert temporär weitere 200 MB. Nachdem `cvsup` seine Arbeit beendet hat, können Sie die Dateien in das Verzeichnis, in dem Sie die Webseiten bauen wollen, auschecken:

    # mkdir /usr/build
    # cd /usr/build
    # cvs -d /usr/dcvs -R co -AP doc www ports

Der letzte Befehl entspricht dem Auschecken der Dateien von einem CVSup-Server mit csup. Danach haben Sie ein Bau-Verzeichis analog zur csup-Methode.

`cvsup` erlaubt es Ihnen auch, Ihr CVS-Repository regelmäßig zu aktualisieren. Im Gegensatz zum ersten Aufruf dauern diese Aktualisierungen in der Regel nur wenige Minuten.

## 8.2. Die Webseiten bauen

Nachdem Sie eine der beiden Methoden erfolgreich ausgeführt haben, können Sie mit dem Bau der Webseiten beginnen. In unserem Beispiel erfolgt der Bau im Verzeichnis ``/usr/build``, in dem sich bereits alle benötigten Dateien befinden.

1. Wechseln Sie in das Bau-Verzeichis.

       # cd /usr/build

2. Sie starten den Bau der Webseiten, indem Sie in das Unterverzeichnis `www/en` wechseln und dort den Befehl make(1) `all` ausführen.

       # cd www/en
       # make all

## 8.3. Installieren der Webseiten auf Ihrem Server

1. Wechseln Sie wieder in das Verzeichnis `en`, falls Sie dieses inzwischen verlassen haben.

       # cd /usr/build/www/en

2. Führen Sie make(1) `install` aus und setzen Sie die Variable `DESTDIR` auf das Verzeichnis, in das Sie die Webseiten installieren wollen. Die daraus resultierenden Dateien werden unter `$DESTDIR/data` installiert, was als die document root ihres Webservers konfiguriert sein sollte.

       # env DESTDIR=/usr/local/www make install

3. Wenn Sie die Webseiten bereits früher in dieses Verzeichnis installiert haben, wurden während der Installation keine veralteten Seiten entfernt. Wenn Sie die Webseiten beispielsweise täglich neu bauen und installieren, findet und entfernt der folgende Befehl alle Dateien, die in den letzten drei Tagen nicht aktualisiert wurden:

       # find /usr/local/www -ctime 3 -print0 | xargs -0 rm

## 8.4. Umgebungsvariablen

`CVSROOT`

  Der Ort des CVS-Baums. Sie sollten diese Variable setzen, wenn Sie die CVSup-Methode verwenden.

      # CVSROOT=/usr/dcvs; export CVSROOT

  `CVSROOT` ist eine Umgebungsvariable. Sie müssen sie daher auf der Kommandozeile oder in Ihren .dot-Dateien (beispielsweise in `~/.profile`) setzen. Die genaue Syntax hängt von der von Ihnen eingesetzten Shell (das letzte Beispiel gilt nur für die bash und bash-ähnliche Shells) ab.

`ENGLISH_ONLY`

  Ist diese Variable gesetzt und nicht leer, bauen und installieren die Makefiles ausschließlich die englischen Dokumente. Sämtliche Übersetzungen werden dabei ignoriert. Dazu ein Beispiel:

      # make ENGLISH_ONLY=YES all install

  Wenn Sie die Variable `ENGLISH_ONLY` deaktivieren und alle Webseiten inklusive aller Übersetzungen bauen wollen, setzen Sie die Variable `ENGLISH_ONLY` auf einen leeren Wert:

      # make ENGLISH_ONLY="" all install clean

`WEB_ONLY`

  Ist diese Variable gesetzt und nicht leer, bauen und installieren die Makefiles nur die HTML-Seiten des Verzeichnisses `www`. Alle Dokumente des `doc`-Verzeichnisses (Handbuch, FAQ, Artikel) werden dabei ignoriert:

      # make WEB_ONLY=YES all install

`WEB_LANG`

  Ist diese Variable gesetzt, wird die Dokumentation nur für die durch diese Variable festgelegten Sprachen gebaut und im Verzeichnis `www` installiert. Alle weiteren Sprachen (ausgenommen Englisch) werden ignoriert. Dazu ein Beispiel:

      # make WEB_LANG="el es hu nl" all install

`NOPORTSCVS`

  Ist diese Variable gesetzt, checken die Makefiles keine Dateien aus dem Ports-CVS-Repository aus. Stattdessen werden die Dateien aus dem Verzeichnis `/usr/ports` (oder aus dem Verzeichnis, auf das die Variable `PORTSBASE` zeigt) verwendet.

`WEB_ONLY`, `ENGLISH_ONLY`, `WEB_LANG` und `NOPORTSCVS` sind Variablen für Makefiles. Diese werden entweder in `/etc/make.conf`, in `Makefile.inc` oder als Umgebungsvariablen auf der Kommandozeile oder in Ihrer Konfigurationsdatei gesetzt.

# Kapitel 9. Übersetzungen

Übersetzt von Johann Kois.

Dieses Kapitel enthält die FAQ für die Übersetzung der FreeBSD Dokumentation (FAQ, Handbuch, Artikel, Manualpages und sonstige Dokumente) in andere Sprachen.

Es beruht sehr stark auf den Übersetzungs-FAQ des FreeBSD German Documentation Projects, die ursprünglich von Frank Gründer `<elwood@mc5sys.in-berlin.de>` geschrieben und danach von Bernd Warken `<bwarken@mayn.de>` ins Englische übersetzt wurden.

Diese FAQ wird vom Documentation Engineering Team `<doceng@FreeBSD.org>` gepflegt.

9.1. Warum eine FAQ?
9.2. Was bedeuten die Abkürzungen i18n und l10n?
9.3. Gibt es eigene Mailinglisten für Übersetzer?
9.4. Werden noch Übersetzer benötigt?
9.5. Welche Sprachen muss ich dafür kennen/können?
9.6. Welche Software wird benötigt?
9.7. Wie finde ich heraus, ob noch jemand Teile der Dokumentation in die gleiche Sprache übersetzt?
9.8. Niemand übersetzt in meine Sprache. Was soll ich machen?
9.9. Ich habe ein Dokument übersetzt. Wo soll ich es hinschicken?
9.10. Ich arbeite als einziger an der Übersetzung in diese Sprache, wie versende ich meine Übersetzungen?
9.11. Kann ich landes- oder sprachspezifische Informationen in meine Übersetzung aufnehmen?
9.12. Wie lassen sich sprachspezifische Zeichen darstellen?
9.13. Wie spricht man den Leser an?
9.14. Muss ich zusätzliche Informationen in meine Übersetzungen einbauen?

9.1. Warum eine FAQ?

Es melden sich immer mehr Leute auf der Mailingliste freebsd-doc, die Teile der FreeBSD Dokumentation in andere Sprachen übersetzen wollen. Diese FAQ soll die am häufigsten gestellten Fragen beantworten, damit möglichst rasch mit der Übersetzung begonnen werden kann.

9.2. Was bedeuten die Abkürzungen i18n und l10n?

i18n steht für internationalization (Internationalisierung), l10n für localization (Lokalisierung). Es handelt sich dabei um besser handhabbare Abkürzungen dieser Begriffe.

i18n kann als i, gefolgt von 18 Buchstaben, gefolgt von einem n, gelesen werden. Analog steht l10n für l, gefolgt von 10 Buchstaben, gefolgt von einem n.

9.3. Gibt es eigene Mailinglisten für Übersetzer?

Ja. Die verschiedenen Übersetzergruppen haben jeweils eigene Mailinglisten. Genauere Informationen finden Sie in der Liste der Übersetzungsprojekte. Diese Liste enthält die Mailinglisten und Internetseiten, die von den einzelnen Übersetzungsprojekten betrieben werden.

9.4. Werden noch Übersetzer benötigt?

Ja. Je mehr Leute an der Übersetzung arbeiten, desto schneller wird diese fertig, und umso schneller sind Änderungen im englischen Original auch in den übersetzten Dokumenten vorhanden.

Sie müsssen kein professioneller Dolmetscher sein, um dabei zu helfen.

9.5. Welche Sprachen muss ich dafür kennen/können?

Idealerweise haben Sie gute Kenntnisse in geschriebenem Englisch, außerdem sollten Sie natürlich fit in der Sprache sein, in die Sie übersetzen wollen.

Englisch ist allerdings nicht unbedingt nötig. Sie könnten beispielsweise auch die FAQ vom Spanischen ins Ungarische übersetzen.

9.6. Welche Software wird benötigt?

Es ist sehr empfehlenswert, eine lokale Kopie des FreeBSD CVS-Repository (als Minimum den Dokumentationsteil) anzulegen, entweder mit CTM oder mit CVSup. Das Kapitel Das Neueste und Beste des Handbuchs beschreibt die Nutzung dieser Programme.

Sie sollten außerdem mit CVS vertraut sein. Damit ist es möglich, festzustellen, was sich zwischen einzelnen Versionen eines Dokuments geändert hat.

[XXX Aufgabe -- Ein Tutorial schreiben, das die Verwendung von CVSup beschreibt, um die Dokumentation herunterzuladen, auszuchecken und festzustellen, was sich zwischen zwei Versionen geändert hat.]

9.7. Wie finde ich heraus, ob noch jemand Teile der Dokumentation in die gleiche Sprache übersetzt?

Die Übersetzungsseite des Documentation Projects listet alle Übersetzungs-Teams auf, die derzeit aktiv sind. Arbeitet bereits jemand an der Übersetzung in Ihre Sprache, so kontaktieren Sie dieses Team, damit Dokumente nicht unnötigerweise mehrfach übersetzt werden.

Wenn Ihre Sprache nicht aufgeführt ist, senden Sie bitte eine E-Mail an das FreeBSD documentation project. Vielleicht denkt ja jemand über eine Übersetzung nach, hat sich aber noch nicht dafür entschieden.

9.8. Niemand übersetzt in meine Sprache. Was soll ich machen?

Gratulation, Sie haben gerade das FreeBSD `Ihre-Sprache` Documentation Translation Project gestartet. Willkommen.

Entscheiden Sie zuerst, ob Sie die dafür nötige Zeit zur Verfügung haben. Da Sie als Einziger an der Übersetzung in Ihre Sprache arbeiten, sind Sie dafür verantwortlich, Ihre Arbeit zu veröffentlichen und die Arbeit von Freiwilligen, die Ihnen dabei helfen wollen, zu koordinieren.

Senden Sie eine E-Mail an die Mailingliste des Documentation Projects, in der Sie bekanntgeben, dass Sie an der Übersetzung der Dokumentation arbeiten, damit die Internetseiten aktualisiert werden können.

Gibt es in Ihrem Land einen FreeBSD-Spiegelserver, so sollten Sie den dafür Zuständigen kontaktieren und nachfragen, ob er Ihnen Speicherplatz oder E-Mailadressen für Ihr Projekt zur Verfügung stellen würde.

Danach wählen Sie ein Dokument aus und beginnen mit der Übersetzung. Am besten beginnen Sie mit kleineren Dateien, beispielsweise den FAQ oder einem der Artikel.

9.9. Ich habe ein Dokument übersetzt. Wo soll ich es hinschicken?

Das kommt darauf an. Wenn Sie bereits in einem Übersetzer-Team arbeiten (etwa dem japanischen oder dem deutschen Team), dann sollten Sie deren Richtlinien zum Umgang mit neuer Dokumentation folgen, die auf deren Internetseiten beschrieben werden.

Wenn Sie die einzige Person sind, die an der Übersetzung in eine Sprache arbeitet, oder wenn Sie für ein Übersetzungsprojekt verantwortlich sind, und Ihre Aktualisierungen an das FreeBSD Project übermitteln wollen, sollten Sie Ihre Übersetzungen dorthin senden (lesen Sie dazu auch die nächste Frage).

9.10. Ich arbeite als einziger an der Übersetzung in diese Sprache, wie versende ich meine Übersetzungen?

oder

Wir sind ein Übersetzer-Team, und wollen Dokumente versenden, die unsere Mitglieder übersetzt haben?

Stellen Sie zuerst sicher, dass Ihre Übersetzungen korrekt organisiert sind. Sie sollte sich also im existierenden Dokumentationsbaum befinden, und ohne Fehler bauen lassen.

Zurzeit wird die FreeBSD Dokumentation unterhalb des Verzeichnisses `doc/` gespeichert. Die direkten Unterverzeichnisse werden entsprechend der Sprachkodierung benannt, in der sie geschrieben sind. Diese Kodierung nach ISO639 finden Sie auf einem FreeBSD-System unter `/usr/share/misc/iso639`, vorausgesetzt, das System wurde nach dem 20. Januar 1999 gebaut.

Wenn in Ihrer Sprache mehrere Kodierungen (wie dies etwa für Chinesisch der Fall ist) vorhanden sind, existiert für jede Kodierung ein eigenes Unterverzeichnis.

Zuletzt existieren auch noch Verzeichnisse für die einzelnen Dokumente.

Die Verzeichnishierarchie für eine hypothetische schwedische Übersetzung könnte etwa so aussehen:

    doc/
        sv_SE.ISO8859-1/
                         Makefile
                         books/
                               faq/
                                   Makefile
                                   book.sgml

Bei `sv_SE.ISO8859-1` handelt es sich um den Namen der Übersetzung in der ``lang`.`encoding`` Form. Beachten Sie auch, dass zum Bauen der Dokumentation zwei Makefiles notwendig sind.

Komprimieren Sie Ihre Übersetzungen mit tar(1) und gzip(1) und senden Sie sie an das FreeBSD Project.

    % cd doc
    % tar cf swedish-docs.tar sv_SE.ISO8859-1
    % gzip -9 swedish-docs.tar

Legen Sie das Archiv `swedish-docs.tar.gz` irgendwo ab. Wenn Sie keinen eigenen Webspace haben (etwa weil Ihr Internetprovider Ihnen keinen zur Verfügung stellt), können Sie auch eine E-Mail an das Documentation Engineering Team `<doceng@FreeBSD.org>` schicken, um abzuklären, ob Sie die Datei auch als E-Mail schicken können.

In beiden Fällen sollten Sie mit send-pr(1) einen Bericht über den Versand der Dokumentation erstellen. Es ist sehr hilfreich, wenn Sie Ihre Übersetzung vorher korrekturlesen lassen und überprüfen, da es unwahrscheinlich ist, dass der Committer Ihre Sprache sehr gut beherrscht.

Danach wird jemand (meistens der Documentation Project Manager, derzeit ist dies das Documentation Engineering Team `<doceng@FreeBSD.org>`) überprüfen, ob sich Ihre Übersetzungen problemlos bauen lassen. Dabei wird besonders auf folgende Punkte geachtet:

1. Verwenden alle Dateien RCS-Strings (wie "ID")?

2. Arbeitet `make all` im Verzeichnis `sv_SE.ISO8859-1` korrekt?

3. Funktioniert `make install` ohne Probleme?

Gibt es dabei Probleme, so wird die Person, die Ihren Beitrag durchsieht, sich wieder an Sie wenden, damit Sie das Problem beheben.

Treten keine Probleme auf, wird Ihre Übersetzung so rasch als möglich committed.

9.11. Kann ich landes- oder sprachspezifische Informationen in meine Übersetzung aufnehmen?

Wir bitten Sie, dies nicht zu tun.

Nehmen wir an, dass Sie das Handbuch ins Koreanische übersetzen und einen Abschnitt mit Händlerinformationen in das Handbuch aufnehmen wollen.

Es gibt keinen Grund, warum diese Information nicht auch in der englischen (oder der deutschen, oder der spanischen, oder der japanischen oder der ...) Version vorhanden sein sollte. Es ist etwa denkbar, dass sich jemand mit englischer Muttersprache während eines Aufenthalts in Korea eine FreeBSD-Kopie kaufen möchte. Außerdem wird dadurch die weltweite Präsenz von FreeBSD verdeutlicht, was natürlich ebenfalls von Vorteil ist.

Wenn Sie also länderspezifische Informationen ergänzen wollen, sollten Sie dies zuerst in der englischen Version (mittels send-pr(1)) tun, und die Änderung anschließend in Ihre Sprache übersetzen.

Vielen Dank.

9.12. Wie lassen sich sprachspezifische Zeichen darstellen?

Nicht-ASCII-Zeichen innerhalb der Dokumentation werden durch SGML-Entities dargestellt.

Diese bestehen aus: Kaufmännischem Und (&), den Namen der Entity, und einem Strichpunkt (;).

Die Namen der Entities sind in ISO8879 definiert, die als Port `textproc/iso8879` installiert werden kann.

Dazu einige Beispiele:

Entity: &eacute;

Darstellung: é

Beschreibung: Kleines e mit (akutem) Akzent

Entity: &Eacute;

Darstellung: É

Beschreibung: Großes E mit (akutem) Akzent

Entity: &uuml;

Darstellung: ü

Beschreibung: Kleines Umlaut-u

Nachdem Sie den iso8879-Port installiert haben, ist die vollständige Liste unter `/usr/local/share/sgml/iso8879` vorhanden.

9.13. Wie spricht man den Leser an?

In englischen Dokumenten wird der Leser mit you angesprochen, es wird nicht zwischen formeller/informeller Anrede unterschieden, wie dies in manchen anderen Sprachen der Fall ist.

Wenn Sie in eine Sprache übersetzen, die diese Unterscheidung trifft, verwenden Sie die Form, die auch in den anderen technischen Dokumentationen dieser Sprache verwendet wird. Für deutsche Versionen ist dies die dritte Person Plural (Sie).

9.14. Muss ich zusätzliche Informationen in meine Übersetzungen einbauen?

Ja.

Der Header der englischen Version jedes Textes sieht in etwa so aus:

    <!--
         The FreeBSD Documentation Project

         $FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml,v 1.5 2000/07/07 18:38:38 dannyboy Exp $
    -->

Das exakte Aussehen kann unterschiedlich sein, die Zeile mit $FreeBSD$ sowie der Ausdruck `The FreeBSD Documentation Project` sind allerdings immer enthalten. Beachten Sie, dass die Zeile mit $FreeBSD von CVS automatisch expandiert wird, daher sollte an dieser Stelle in Ihren neuen Dokumenten nur `$FreeBSD$` stehen.

Ihre übersetzten Dokumente sollten eine eigene $FreeBSD$-Zeile enthalten. Zusätzlich sollten Sie die Zeile mit `The FreeBSD Documentation Project` in `The FreeBSD `Ihre-Sprache` Documentation Project` ändern.

Außerdem sollten Sie eine weitere Zeile einfügen, die festlegt, auf welcher Version des englischen Originals Ihre Übersetzung basiert.

Die spanische Version dieser Datei könnte etwa so beginnen:

    <!--
         The FreeBSD Spanish Documentation Project

         $FreeBSD: doc/es_ES.ISO8859-1/books/fdp-primer/translations/chapter.sgml,v 1.3 1999/06/24 19:12:32 jesusr Exp $
         Original revision: 1.11
    -->

# Kapitel 10. Der Schreibstil

Übersetzt von Johann Kois.

Damit von verschiedenen Autoren geschriebene Dokumente zueinander konsistent bleiben, gibt es einige Richtlinien, denen Autoren bei der Erstellung ihrer Dokumente folgen müssen.

Verwendung von amerikanischem Englisch

  Es gibt mehrere englische Varianten und damit verbunden verschiedene Schreibweisen für das gleiche Wort. Wo dies der Fall ist, ist die amerikanische Schreibweise zu verwenden. Man schreibt daher color statt colour, rationalize statt rationalise, und so weiter.

  > Anmerkung: Die Verwendung von Britischem Englisch ist akzeptabel, wenn es sich um einen neuen Beitrag handelt, solange die gesamte Schreibweise eines Dokuments einheitlich bleibt. Alle anderen Dokumente wie Bücher, Internetseiten, Manualpages und andere müssen allerdings amerikanisches Englisch verwenden.

Vermeiden von Zusammenziehungen

  Verwenden Sie keine Zusammenziehungen, sondern schreiben Sie die Phrase immer aus. Die Schreibweise Don't use contractions. wäre also nicht korrekt.

  Die Vermeidung von Zusammenziehungen sorgt für einen etwas formelleren Ton, ist präziser und erleichtert die Arbeit der Übersetzer.

Nutzung von Kommas bei Aufzählungen

  Bei einer Aufzählung innerhalb eines Absatzes sollten Sie zwischen den einzelnen Begriffen Kommas setzen. Zwischen dem letzten und vorletzten Begriff setzen Sie ein Komma und das Wort und.

  Dazu ein Beispiel:

  > Das ist eine Liste von ein, zwei und drei Dingen.

  Handelt es sich dabei um eine Liste von drei Begriffen, ein, zwei, und drei, oder um eine Liste von zwei Begriffen, ein und zwei und drei?

  Es ist daher besser, explizit ein serielles Komma zu setzen:

  > Das ist eine Liste von ein, zwei, und drei Dingen.

Vermeidung von redundanten Begriffen

  Versuchen Sie, keine redundanten Phrasen zu verwenden. Dies gilt insbesondere für die Ausdrücke der Befehl, die Datei, und man command.

  Die folgenden zwei Beispiele veranschaulichen dies für Befehle. Bevorzugt wird die Schreibweise des zweiten Beispiels.

  Verwenden Sie den Befehl `cvsup`, um Ihre Quellen zu aktualisieren.

  Verwenden Sie `cvsup`, um Ihre Quellen zu aktualisieren.

  Analoges gilt für Dateinamen, wobei wiederum die zweite Schreibweise bevorzugt wird.

  ... in der Datei `/etc/rc.local`...

  ... in `/etc/rc.local`...

  Auch für Manualpages gibt es zwei Schreibweisen. Auch hier wird die zweite Schreibweise bevorzugt (das zweite Beispiel nutzt das Tag `<citerefentry>`).

  Weitere Informationen finden Sie in `man csh`.

  Weitere Informationen finden Sie in csh(1).

Zwei Leerzeichen am Satzende

  Verwenden Sie immer zwei Leerzeichen am Ende eines Satzes. Dadurch erhöht sich die Lesbarkeit des Textes und die Nutzung von Werkzeugen wie Emacs wird vereinfacht.

  Nun könnte man behaupten, dass ein Punkt vor einem Großbuchstaben das Satzende markiert. Vor allem bei Namen, beispielsweise bei Jordan K. Hubbard, ist dies allerdings nicht der Fall. Wir haben hier ein großes `K`, gefolgt von einem Punkt und einem Leerzeichen. Dennoch handelt es sich nicht um den Anfang eines neuen Satzes.

Eine ausführliche Beschreibung des korrekten Schreibstils finden Sie im Buch Elements of Style von William Strunk.

## 10.1. Anleitungen für einen korrekten Schreibstil

Damit die Quellen der Dokumentation selbst dann konsistent bleiben, wenn viele Leute daran arbeiten, folgen Sie bitte den folgenden Konventionen.

### 10.1.1. Groß- und Kleinschreibung

Tags werden in Kleinbuchstaben geschrieben, Sie schreiben also `<para>`, nicht `<PARA>`.

Text im SGML-Kontext wird hingegen in Großbuchstaben geschrieben. Man schreibt also `<!ENTITY...>` und `<!DOCTYPE...>`, nicht `<!entity...>` und `<!doctype...>`.

### 10.1.2. Abkürzungen (Akronyme)

Abkürzungen sollten bei ihrer ersten Verwendung immer ausgeschrieben werden. Man schreibt also beispielsweise Network Time Protocol (NTP). Nachdem die Abkürzung definiert wurde, sollte hingegen nur noch die Abkürzung verwendet werden, es sei denn, die Verwendung des gesamten Begriffes ergibt im jeweiligen Kontext mehr Sinn. Im Normalfall werden Akronyme in jedem Dokument nur einmal definiert. Es ist allerdings auch möglich, sie für jedes Kapitel erneut zu definieren.

Die drei ersten Vorkommen der Abkürzung sollten in `<acronym>`-Tags eingeschlossen werden. Zusätzlich wird ein `role`-Attribut mit dem vollständigen Begriff definiert. Dadurch kann ein Link zu einem Glossar erzeugt werden. Außerdem wird der komplette Begriff angezeigt, wenn man den Mauscursor über die Abkürzung bewegt.

### 10.1.3. Einrückung

Die erste Zeile jeder Datei hat die Einrückung 0, und zwar unabhängig von der Einrückung der Datei, in der sie enthalten ist.

Öffnende Tags erhöhen die Einrückung um zwei Leerzeichen. Schließende Tags verringern sie hingegen um zwei Leerzeichen. Ein Block von acht Leerzeichen wird durch einen Tabulator ersetzt. Ein solcher Block beginnt immer am Anfang einer Zeile, führende Leerzeichen sind hier also nicht erlaubt. Vermeiden Sie außerdem Leerzeichen am Zeilenende. Der Inhalt von Elementen wird um zwei Leerzeichen eingerückt, wenn er sich über mehr als eine Zeile erstreckt.

Der Quellcode dieses Abschnitts sieht daher in etwa so aus:

    +--- Einr&uuml;ckung (Spalte) 0
    V
    <chapter>
      <title>...</title>

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

        <sect2>
          <title>Einr&uuml;ckung</title>

          <para>Die erste Zeile jeder Datei hat die Einr&uuml;ckung 0, und
            zwar <emphasis>unabh&auml;ngig</emphasis> von der Einr&uuml;ckung
            der Datei, in der sie enthalten ist.</para>

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

Wenn Sie Emacs oder XEmacs verwenden, um Ihre Dateien zu bearbeiten, sollte der `sgml-mode` automatisch geladen werden, und die lokalen Emacs-Variablen am Ende einer Datei sollten diesen Stil erzwingen.

Verwenden Sie Vim, sollten Sie Ihren Editor so konfigurieren:

    augroup sgmledit
      autocmd FileType sgml set formatoptions=cq2l " Special formatting options
      autocmd FileType sgml set textwidth=70       " Wrap lines at 70 columns
      autocmd FileType sgml set shiftwidth=2       " Automatically indent
      autocmd FileType sgml set softtabstop=2      " Tab key indents 2 spaces
      autocmd FileType sgml set tabstop=8          " Replace 8 spaces with a tab
      autocmd FileType sgml set autoindent         " Automatic indentation
    augroup END

### 10.1.4. Die korrekte Schreibweise von Tags

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

### 10.1.5. Markup-Änderungen (white space changes)

Wenn Sie Änderungen committen, committen Sie niemals Inhalts- und Formatierungsänderungen zur gleichen Zeit.

Nur auf diese Weise können die Übersetzungs-Teams sofort erkennen, welche Änderungen durch Ihren Commit verursacht wurden, ohne darüber nachdenken zu müssen, ob sich der Inhalt einer Zeile oder nur deren Formatierung geändert hat.

Nehmen wir an, Sie haben zwei Sätze in einen Absatz eingefügt. Daher sind zwei Zeilen nun länger als 80 Zeichen. Zuerst committen Sie Ihre inhaltliche Änderung inklusive der zu langen Zeilen. Im nächsten Commit korrigieren Sie den Zeilenumbruch und geben in der Commit-Mitteilung an, dass es sich nur um Änderung am Markup handelt (whitespace-only change), und Übersetzer den Commit daher ignorieren können.

### 10.1.6. Vermeiden von fehlerhaften Zeilenumbrüchen (Nutzung von non-breaking space)

Vermeiden Sie Zeilenumbrüche an Stellen, an denen diese hässlich aussehen oder es erschweren, einem Satz zu folgen. Zeilenumbrüche hängen von der Breite des gewählten Ausgabemedium ab. Insbesondere bei der Verwendung von Textbrowsern können schlecht formatierte Absätze wie der folgende entstehen:

    Data capacity ranges from 40 MB to 15
    GB.  Hardware compression ...

Die Nutzung der Entity `&nbsp;` verhindert Zeilenumbrüche zwischen zusammengehörenden Teilen. Verwenden Sie non-breaking spaces daher in den folgenden Fällen:

- Zwischen Zahlen und Einheiten:

      57600&nbsp;bps

- Zwischen Programmnamen und Versionsnummern:

      FreeBSD&nbsp;4.7

- Zwischen mehreren zusammengehörenden Wörtern (Vorsicht bei Namen, die aus mehr als 3-4 Wörtern bestehen, wie The FreeBSD Brazilian Portuguese Documentation Project):

      Sun&nbsp;Microsystems

## 10.2. Häufig verwendete Wörter

Die folgende Liste enthält einige Beispiele, wie bestimmte Wörter innerhalb des FreeBSD Documentation Projects geschrieben werden. Finden Sie ein gesuchtes Wort hier nicht, sehen Sie bitte in der Liste häufig verwendeter Wörter von O'Reilly nach.

- 2.2.X

- 4.X-STABLE

- CD-ROM

- DoS (Denial of Service)

- Ports Collection

- IPsec

- Internet

- MHz

- Soft Updates

- Unix

- disk label

- email

- file system

- manual page

- mail server

- name server

- null-modem

- web server

# Kapitel 11. `sgml-mode` und Emacs

Neuere Emacs- und XEmacs-Versionen verfügen über ein nützliches Lisp-Paket namens PSGML. PSGML (das über den Port `editors/psgml` installiert werden kann) ist ein so genannter Majormode, der Funktionen speziell für den Umgang mit SGML-Dateien, -Elementen und deren Attributen bereit stellt. Emacs aktiviert PSGML automatisch, wenn eine Datei mit der Endung `.sgml` geladen oder der Befehl `M-X sgml-mode` eingegeben wird.

Die Arbeit an SGML-Dokumenten wie dem FreeBSD-Handbuch kann sich wesentlich einfacher gestalten, wenn einige der Funktionen von PSGML gekannt sind:

`C-c C-e`

  Ruft die Funktion `sgml-insert-element` auf, die nach dem Namen des einzufügenden Elements fragt. Ist dieser eingegeben worden und wurde die Eingabetaste gedrückt, fügt die Funktion Start- und Endtag des neuen Elements ein. Sofern das eingefügte Element laut DTD andere Elemente enthalten muß, werden diese ebenfalls miteingefügt.

  Falls Sie unsicher sind, wie der Name des gewünschten Elements lautet oder welche Elemente an der aktuellen Position erlaubt sind, können mittels der Taste Tab alle an dieser Stelle möglichen Elemente angezeigt werden. Ebenso ermöglicht Tab die Vervollständigung eines bereits eingegebenen Elementnamens.

`C-c =`

  Ruft die Funktion `sgml-change-element-name` auf, mit der das aktuelle Element - das Element zwischen dessen Start- und Endtag sich der Cursor befindet - ausgewechselt werden kann. Die Funktion fragt nach dem Namen des neuen Elements und ersetzt anschließend Start- und Endtag des alten Elements durch die des neuen Elements.

`C-c C-r`

  Ruft die Funktion `sgml-tag-region` auf, die einen markierten Textabschnitt mit einem Element umschließt. Dazu markieren Sie zuerst den Textabschnitt (gehen Sie zum Anfang des Abschnitts und führen Sie `C-space` aus, dann gehen Sie zum Ende des Abschnitts und führen erneut `C-space` aus), danach führen Sie diese Funktion aus. Sie werden nach dem Namen des einzufügenden Elements gefragt. Dessen Start-Tag wird dann am Anfang des markierten Textes eingefügt, dessen End-Tag am Ende des markierten Texts.

`C-c -`

  Ruft die Funktion `sgml-untag-element` auf, die Start- und Endtag des Elements entfernt, innerhalb dessen sich der Cursor befindet.

`C-c C-q`

  Ruft die Funktion `sgml-fill-element` auf. Diese Funktion formatiert[18] den Inhalt des aktuellen Elements neu. Dieser Vorgang betrifft auch Elemente wie `<programlisting>`, in denen Leerzeichen und ähnliches Teil der Formatierung sind. Aus diesem Grund ist mit `sgml-fill-element` bedächtig umzugehen.

`C-c C-a`

  Ruft die Funktion `sgml-edit-attributes` auf. Diese öffnet einen zweiten Puffer mit allen Attributen des Elements, innerhalb dessen sich der Cursor befindet. Über Tab kann von einem Attribut zum nächsten gewechselt werden. Ein existierender Attributwert kann mit `C-k` gelöscht werden. Die Tastenfolge `C-c C-c` schließt den Puffer und setzt die Attribute des Elements entsprechend den Puffervorgaben.

`C-c C-v`

  Ruft die Funktion `sgml-validate` auf, die zuerst fragt, ob das aktuelle Dokument gespeichert werden soll und anschließend einen SGML-Validator aufruft. Die Ausgaben des Validators werden in einem neuen Puffer angezeigt. Dadurch hat der Benutzer die Möglichkeit, eventuell vom Validator gefundene Fehler zu korrigieren.

`C-c /`

  Startet die Funktion `sgml-insert-end-tag`, die automatisch das passende End-Tag für das gerade offene Element einfügt.

Zweifellos hat PSGML noch weitere nützliche Funktionen, doch die hier genannten sind die, die der Autor dieser Fibel am meisten benutzt.

Um den richtigen Einzug, die Umwandlung von Tabulatoren in Leerzeichen und die maximale Zeilenlänge für Dokumente des FDPs sicherzustellen, kann folgender Eintrag in `.emacs` vorgenommen werden:

        (defun local-sgml-mode-hook
          (setq fill-column 70
                indent-tabs-mode nil
                next-line-add-newlines nil
                standard-indent 4
                sgml-indent-data t)
          (auto-fill-mode t)
          (setq sgml-catalog-files '("/usr/local/share/sgml/catalog")))
        (add-hook 'psgml-mode-hook
          '(lambda () (local-psgml-mode-hook)))

# Kapitel 12. Weiterführende Quellen

In dieser Fibel werden absichtlich nicht alle Aspekte von SGML, der erwähnten DTDs und des FreeBSD-Dokumentationsprojekts behandelt. Interessierten werden daher die nachfolgenden Quellen empfohlen.

## 12.1. Das FreeBSD-Dokumentationsprojekt

- Die Webseiten des FreeBSD-Dokumentationsprojektes

- Das FreeBSD-Handbuch

## 12.2. SGML

- Die SGML/XML-Webseite, eine umfangreiche Quelle zu SGML.

- Gentle introduction to SGML

## 12.3. HTML

- Das World-Wide-Web-Konsortium

- Die HTML 4.0-Spezifikation

## 12.4. DocBook

- The DocBook Technical Committee, die Betreuer der DocBook-DTD.

- DocBook: The Definitive Guide, die Online-Dokumentation zur DocBook-DTD.

- The DocBook Open Repository bietet DSSSL-Stilvorlagen und andere Ressourcen für DocBook-Benutzer an.

## 12.5. Das Linux-Dokumentationsprojekt

- Die Webseiten des Linux-Dokumenationsprojektes.

# Anhang A. Beispiele

In diesem Anhang sind SGML-Beispieldokumente und Befehle enthalten, die zeigen, wie man aus DocBook-Dokumenten verschiedene Ausgabeformate erzeugen kann. Sofern alle Werkzeuge für das Dokumentationsprojekt ordnungsgemäß installiert wurden, können die angebotenen Beispiele direkt übernommen werden.

Die Beispiele dieses Abschnitts sind bewusst einfach aufgebaut. Daher fehlen in den Beispielen einige Elemente, insbesondere Elemente für die Titelei. Weitere DocBook-Beispiele können in den DocBook-Quellen dieses und anderer Dokumente des FDPs gefunden werden. Die Quellen des FDPs sind über CVSup und online unter http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/ verfügbar.

Um Irritationen zu vermeiden, bauen die SGML-Beispiele auf der 4.1er Standard-DocBook DTD anstatt auf der erweiterten FreeBSD-Variante auf. Ebenso werden die Standardstylesheets von Norman Welsh, anstatt der angepassten Stylesheets des FreeBSD-Dokumentationsprojektes benutzt. Dadurch eignen sich die Beispiele auch als generische DocBook-Vorlagen.

## A.1. DocBook-Buch (`<book>`)

Beispiel A-1. Ein DocBook-Buch (`<book>`)

    <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

    <book>
      <bookinfo>
        <title>Ein Buchbeispiel</title>

        <author>
          <firstname>Vorname</firstname>
          <surname>Nachname</surname>
          <affiliation>
            <address><email>vorname.nachname@domain.de</email></address>
          </affiliation>
        </author>

        <copyright>
          <year>2000</year>
          <holder>Urheberhinweis</holder>
        </copyright>

        <abstract>
          <para>Falls das Buch eine Zusammenfassung hat, sollte sie
            hier stehen.</para>
        </abstract>
      </bookinfo>

      <preface>
        <title>Einleitung</title>

        <para>Falls das Buch eine Einleitung hat, sollte diese hier
          stehen.</para>
      </preface>

      <chapter>
        <title>Das erste Kapitel</title>

        <para>Das ist das erste Kapitel des Buches.</para>

        <sect1>
          <title>Der erste Abschnitt</title>

          <para>Das ist der erste Abschnitte des Buches.</para>
        </sect1>
      </chapter>
    </book>

## A.2. DocBook-Artikel (`<article>`)

Beispiel A-2. Ein DocBook-Artikel (`<article>`)

    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

    <article>
      <articleinfo>
        <title>Ein Beispielartikel</title>

        <author>
          <firstname>Vorname</firstname>
          <surname>Nachname</surname>
          <affiliation>
            <address><email>vorname.nachname@domain.de</email></address>
          </affiliation>
        </author>

        <copyright>
          <year>2000</year>
          <holder>Urheberhinweis</holder>
        </copyright>

        <abstract>
          <para>Falls der Artikel eine Zusammenfassung hat, sollte sie
            hier stehen.</programlisting>
        </abstract>
      </articleinfo>

      <sect1>
        <title>Der erste Abschnitt</title>

        <para>Das ist der erste Abschnitt des Artikels.</para>

        <sect2>
          <title>Der erste Unterabschnitt</title>

          <para>Das ist der erste Unterabschnitt des Artikels.</para>
        </sect2>
      </sect1>
    </article>

## A.3. Ausgabeformate erzeugen

Für diesen Abschnitt wird vorausgesetzt, dass die im Port `textproc/docproj` enthaltene Software manuell oder über das Portssystem installiert wurde. Weiter wird vorausgesetzt, dass alle Programme unterhalb des Verzeichnisses `/usr/local` installiert worden sind und die Verzeichnisse, die die ausführbaren Programme enthalten, in der Variable `PATH` enthalten sind.

### A.3.1. Benutzung von Jade

Beispiel A-3. Ein DocBook-Dokument in eine einzelne HTML-Datei umwandeln

    % jade -V nochunks \
    -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \
    -c /usr/local/share/sgml/docbook/catalog \
    -c /usr/local/share/sgml/jade/catalog \
    -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \
    -t sgml  datei.sgml > datei.html

  Übergibt den Parameter `nochunks` an die Stylesheets. Dadurch wird die gesamte Ausgabe in die Standardausgabe geschrieben (bei der Benutzung von Norm Walshs Stylesheets).
  Legt die von Jade zur Verarbeitung benötigten drei Kataloge fest. Der erste Katalog enthält Informationen zu den DSSSL-Stylesheets, der zweite zur DocBook DTD und der dritte Jade-spezifische Informationen.
  Übergibt den vollen Pfad zum DSSSL-Stylesheet, das von Jade zur Verarbeitung des Dokuments benutzt wird.
  Weist Jade an, eine Transformation von einer DTD zu einer anderen DTD vorzunehmen. In diesem Falle, von der DocBook DTD zur HTML DTD.
  Legt fest, welche Datei Jade verarbeiten soll und leitet die Ausgabe in die Datei `datei.html` um.

Beispiel A-4. Ein DocBook-Dokument in mehrere kleine HTML-Dateien umwandeln

    % jade \
    -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \
    -c /usr/local/share/sgml/docbook/catalog \
    -c /usr/local/share/sgml/jade/catalog \
    -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \
    -t sgml  datei.sgml

  Legt die von Jade zur Verarbeitung benötigten drei Kataloge fest. Der erste Katalog enthält Informationen zu den DSSSL-Stylesheets, der zweite zur DocBook DTD und der dritte Jade-spezifische Informationen.
  Übergibt den vollen Pfad zum DSSSL-Stylesheet, das von Jade zur Verarbeitung des Dokuments benutzt wird.
  Weist Jade an, eine Transformation von einer DTD zu einer anderen DTD vorzunehmen. In diesem Falle, von der DocBook DTD zur HTML DTD.
  Legt die zu verarbeitende Datei fest. Die Stylesheets ermitteln eigenständig die Namen aller HTML-Ausgabedateien.

Abhängig von der Struktur des zu verarbeitenden Dokumentes und den Stylesheetregeln zur Aufteilung des Dokumentes, kann dieser Befehl auch nur eine einzelne HTML-Datei erzeugen.

Beispiel A-5. Ein DocBook-Dokument nach Postscript umwandeln

Um eine Postscript-Ausgabe zu erzeugen, muss zuerst die SGML-Quelle in eine TeX-Datei umgewandelt werden.

    % jade -V tex-backend \
        -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \
        -c /usr/local/share/sgml/docbook/catalog \
        -c /usr/local/share/sgml/jade/catalog \
        -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl \
        -t tex  datei.sgml

  Weist die Stylesheets an, verschiedene TeX-spezifische Optionen zu benutzen.
  Legt die von Jade zur Verarbeitung benötigten drei Kataloge fest. Der erste Katalog enthält Informationen zu den DSSSL-Stylesheets, der zweite zur DocBook DTD und der dritte Jade-spezifische Informationen.
  Übergibt den vollen Pfad zum DSSSL-Stylesheet, das von Jade zur Verarbeitung des Dokuments benutzt wird.
  Weist Jade an, die Ausgabe in eine TeX-Datei umzuwandeln.

Die so erzeugte `.tex`-Datei muss anschließend mittels `tex`, unter Angabe des Makropakets `&jadetex` weiterverarbeitet werden.

    % tex "&jadetex" datei.tex

`tex` muss mindestens dreimal ausgeführt werden. Der erste Lauf ermittelt die die Querverweise innerhalb des Dokumentes, die für Stichwortverzeichnisse und ähnliches benötigt werden.

Warnungen, wie `LaTeX Warning: Reference `136' on page 5 undefined on input line 728.`, die zu diesem Zeitpunkt ausgegeben werden, können ohne weiteres ignoriert werden.

Der zweite Lauf kann jetzt, da mehr Informationen, wie zum Beispiel die Seitenlängen, zur Verfügung stehen, Einträge im Stichwortverzeichnis und Querverweise genauer bestimmen.

Der dritte Lauf ist für abschließende Aufräumarbeiten notwendig. Die so von `tex` erzeugte Ausgabe befindet sich anschließend in der Datei ``datei`.div`.

Zum Schluss muss noch `dvips` aufgerufen werden, um die `.div`-Datei in ein Postscript-Dokument umzuwandeln.

    % dvips -o datei.ps datei.dvi

Beispiel A-6. Eine PDF-Datei aus einem DocBook-Dokument erzeugen

Die ersten Schritte, um ein DocBook-Dokument in ein PDF umzuwandeln, stimmen mit denen überein, die notwendig sind, um eine Postscript-Ausgabe zu erzeugen (Beispiel A-5).

Nachdem die `.tex`-Datei durch Jade erzeugt wurde, muss pdfTeX stattdessen mit dem Makropaket `&pdfjadetex` aufgerufen werden.

    % pdftex "&pdfjadetex" datei.tex

Dieser Befehl muss ebenfalls dreimal ausgeführt werden. Am Ende liegt mit ``datei`.pdf` das fertige PDF-Dokument vor. Weitere Schritte sind jetzt nicht mehr notwendig.

### Fußnoten

[1] | Im angelsächischschen Sprachraum wird von markup gesprochen.
[2] | Bei natürlichen Sprachen spricht man vom Satzbau - demjenigen Konstrukt, das unter anderem die Position des Subjekts, Objekts und Prädikats in einem Satz festlegt.
[3] | Im angelsächsichen Sprachraum wird hier von chunking gesprochen.
[4] | Sofern man nicht an der deutschen Dokumentation arbeitet, müssen die Verzeichnisangaben entsprechend angepasst werden.
[5] | auf Englisch Formal Public Identifier (FPI)
[6] | Es wird das Prozentzeichen anstelle des kaufmännischen Unds verwendet.
[7] | Eigentlich ist das eine Schande. Man stelle sich vor, welche Probleme und Hacks, wie beispielsweise Server Side Includes, man an dieser Stelle hätte vermeiden können.
[8] | auf Englisch marked sections
[9] | auf Englisch character data
[10] | auf Englisch Entity references and character data
[11] | Die englische Bezeichnung inline element wurde in Anlehnung an das Wort Fließtext mit Flußelement übersetzt.
[12] | Der Standardwert für `size` ist `3`.
[13] | Einen kurzen historischen Abriss finden Sie unter http://www.oasis-open.org/docbook/intro.shtml#d0e41.
[14] | DocBook kennt noch andere Elemente für die Auszeichnung von Listen, die an dieser Stelle jedoch nicht behandelt werden.
[15] | auf Englisch: callout
[16] | 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.
[17] | Der Befehl `mozilla` startet das Programm mozilla.
[18] | Formatieren bedeutet in diesem Zusammenhang, dass die Funktion versucht, soviel Zeichen wie möglich in einer Zeile unterzubringen. Die Stelle, bis zu der gefüllt und dann der Zeilemumbruch erfolgt, ist konfigurierbar.

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