<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
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.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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.
$FreeBSD$
$FreeBSDde$
basiert auf: r38851
-->
<chapter id="sgml-markup">
<title>SGML-Dokumente erstellen</title>
<para>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.</para>
<para>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.</para>
<para>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 &a.doc;
geschickt werden.</para>
<note>
<title>Flu�- kontra Blockelemente</title>
<!--@todo
Fussnote bzgl. der UEbersetzung von "inline" einfuegen.
Oliver Fischer
-->
<para>Wenn im folgenden von
<emphasis>Flu�elementen</emphasis> die Rede ist, sind
damit Elemente gemeint, die in einem Blockelement auftreten
k�nnen und keinen Zeilenumbruch hervorrufen.
<emphasis>Blockelemente</emphasis> hingegen erzeugen unter
anderem einen Zeilenumbruch<footnote><para>Die englische
Bezeichnung <foreignphrase>inline element</foreignphrase>
wurde in Anlehnung an das Wort <quote>Flie�text</quote>
mit <quote>Flu�element</quote>
�bersetzt.</para></footnote>.</para>
</note>
<sect1 id="sgml-markup-html">
<title>HTML</title>
<para>HTML, die <foreignphrase>HyperText Markup
Language</foreignphrase>, ist die Auszeichnungssprache des
Internets. Weitere Informationen zu HTML finden sich unter
<ulink url="http://www.w3.org/"></ulink>.</para>
<para>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.</para>
<para>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: <quote>streng</quote> (HTML 4.0
Strict) und <quote>locker</quote> (HTML 4.0
Transitional).</para>
<para>Die HTML-DTDs sind �ber den Port <filename
role="package">textproc/html</filename> verf�gbar und werden
automatisch als Teil des Metaports <filename
role="package">textproc/docproj</filename>
mitinstalliert.</para>
<sect2>
<title>Formale �ffentliche Bezeichner</title>
<!--@todo Optimierungskandidat. Oliver Fischer -->
<para>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.</para>
<programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</sect2>
<sect2>
<title>Die Elemente <sgmltag>head</sgmltag> und
<sgmltag>body</sgmltag></title>
<para>Ein HTML-Dokument unterteilt sich normalerweise in zwei
Bereiche: <quote>head</quote> und <quote>body</quote>. Der
Kopf (<foreignphrase>head</foreignphrase>) enth�lt Metadaten
wie den Dokumententitel und Angaben zum Autor. Der Rumpf
(<foreignphrase>body</foreignphrase>) umfa�t den eigentlichen
Dokumenteninhalt, der f�r den Leser bestimmt ist. In einem
HTML-Dokument werden diese Bereiche �ber die Elemente
<sgmltag>head</sgmltag> und <sgmltag>body</sgmltag>
voneinander abgegrenzt. Beide sind Kinder des Wurzelelementes
<sgmltag>html</sgmltag>.</para>
<example>
<title>Die Struktur eines HTML-Dokumentes</title>
<programlisting><html>
<head>
<title><replaceable>Der Dokumententitel</replaceable></title>
</head>
<body>
…
</body>
</html></programlisting>
</example>
</sect2>
<sect2>
<title>Blockelemente</title>
<sect3>
<title>�berschriften</title>
<para>HTML kennt sechs verschiedene Elemente, mit denen
�berschriften ausgezeichnet werden k�nnen. Das bekannteste
Element ist <sgmltag>h1</sgmltag>, das sich am Anfang der
�berschriftenhierarchie befindet. <sgmltag>h1</sgmltag>
folgen die �berschriftenelemente <sgmltag>h2</sgmltag> bis
<sgmltag>h6</sgmltag>. Der Inhalt von
<sgmltag>h<replaceable>N</replaceable></sgmltag> stellt den
Text der �berschrift dar.</para>
<example>
<title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>…</title>
<para>F�gen Sie in eine der existierenden �bungsdateien folgendes ein:</para>
<programlisting><![CDATA[<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 -->]]></programlisting>
</example>
<para>Eine HTML-Seite sollte immer nur eine �berschrift
<sgmltag>h1</sgmltag> haben. Dieser �berschrift k�nnen
beliebig viele Kapitel mit einer �berschrift
<sgmltag>h2</sgmltag> folgen, die selbst wiederum eine
beliebige Anzahl von Kapiteln mit einer �berschrift
<sgmltag>h3</sgmltag> enthalten k�nnen. Diese
Verschachtelung setzt sich bis zu Kapiteln mit einer
<sgmltag>h6</sgmltag>-�berschrift fort. Es sollte vermieden
werden, Elemente in der �berschriftenhierarchie
auszulassen.</para>
<example>
<title>Falsche Verschachtelung von �berschriften</title>
<para>F�gen Sie in eine der existierenden �bungsdateien folgendes ein:</para>
<programlisting><![CDATA[<h1>Erstes Kapitel</h1>
<!-- Allgemeines zum Dokument -->
<h3>Unterkapitel</h3>
<!-- h3 folgt direkt auf h1. h2 wurde ausgelassen -->]]></programlisting>
</example>
</sect3>
<sect3>
<title>Abs�tze</title>
<para>Abs�tze k�nnen in HTML mit Hilfe des Elementes
<sgmltag>p</sgmltag> ausgezeichnet werden.</para>
<example>
<title>Abs�tze mit dem Element <sgmltag>p</sgmltag></title>
<para>F�gen Sie in eine der existierenden �bungsdateien folgendes ein:</para>
<programlisting><![CDATA[<p>Das hier, das ist ein Absatz. Abs�tze k�nnen
andere Elemente enhalten.</p>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Blockzitate</title>
<para>Ein Blockzitat ist ein etwas umfangreicheres Zitat aus
einem anderen Text, das nicht zum aktuellen Absatz
geh�rt.</para>
<example>
<title>Blockzitat</title>
<para>F�gen Sie in eine der existierenden �bungsdateien
folgendes ein:</para>
<programlisting><![CDATA[<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>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Listen</title>
<para>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.</para>
<para>Sortierte Listen werden mit dem Element
<sgmltag>ol</sgmltag> (f�r
<foreignphrase><emphasis>o</emphasis>rdered
<emphasis>l</emphasis>ist</foreignphrase>) ausgezeichnet,
unsortierte Listen mit <sgmltag>ul</sgmltag> (f�r
<foreignphrase><emphasis>u</emphasis>nordered
<emphasis>l</emphasis>ist</foreignphrase>) und
Definitionslisten mit <sgmltag>dl</sgmltag>.</para>
<para>Listenpunkte sortierter und unsortierter Listen werden
mit dem Element <sgmltag>li</sgmltag> ausgezeichnet,
welches Text oder andere Blockelemente enthalten kann.
Begriffe, die in einer Definitionslisten enthalten sind,
werden mit dem Element <sgmltag>dt</sgmltag> (f�r
<foreignphrase><emphasis>d</emphasis>efinition
<emphasis>t</emphasis>erm</foreignphrase>) ausgezeichnet.
Die Erkl�rung zu diesem Begriff wird mit Hilfe des Elementes
<sgmltag>dd</sgmltag> (f�r <foreignphrase>definition
description</foreignphrase>) markiert. So wie
<sgmltag>li</sgmltag>, kann das Element
<sgmltag>dd</sgmltag> ebenfalls andere Blockelemente
aufnehmen.</para>
<example>
<title>Listen mit <sgmltag>ul</sgmltag> und
<sgmltag>ol</sgmltag> erstellen</title>
<para>F�gen Sie in eine der existierenden �bungsdateien
folgendes ein:</para>
<programlisting><![CDATA[<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>]]></programlisting>
</example>
<example>
<title>Definitionslisten mit <sgmltag>dl</sgmltag> erstellen</title>
<para>F�gen Sie in eine der existierenden �bungsdateien folgendes ein:</para>
<programlisting><![CDATA[<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>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Vorformatierter Text</title>
<!--@todo Bezeichnung ,,Schrift mit fester Laufweite'' Richtig?
Oliver Fischer, 21.03.04 -->
<para>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
<sgmltag>pre</sgmltag> vorgesehen, welches daf�r sorgt, dass
Zeilenumbr�che erhalten bleiben und Leerzeichen nicht
zusammengefa�t werden. Browser verwenden f�r den
Inhalt des Elementes <sgmltag>pre</sgmltag>
�blicherweise eine Fixschrift.</para>
<example>
<title>Vorformatierten Text mit <sgmltag>pre</sgmltag> erstellen</title>
<para>Der Originaltext einer E-Mail l��t sich beispielsweise
wie folgt einbinden:</para>
<!--<para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail
message;</para>-->
<programlisting><![CDATA[<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>]]></programlisting>
<para>Beachten Sie, dass <literal><</literal> und
<literal>&</literal> nach wie vor als Sonderzeichen
erkannt werden. Daher wird in diesem Beispiel auch
<literal>&lt;</literal> an Stelle von
<literal><</literal> verwendet. Aus dem gleichen
Grund wurde auch <literal>&gt;</literal> an Stelle
von <literal>></literal> verwendet. Achten Sie also
stets auf Sonderzeichen, wenn Sie normalen Text
aus E-Mails, Programmcode oder einer anderen Quelle
kopieren.</para>
</example>
</sect3>
<sect3>
<title>Tabellen</title>
<note>
<para>Die meisten Textbrowser, beispielsweise Lynx, k�nnen
Tabellen nicht besonders gut darstellen. Deshalb sollten
Auszeichnungsalternativen in Betracht gezogen werden, um
eine angemessene Darstellung sicherzustellen.</para>
</note>
<para>Tabellen lassen sich in HTML mit Hilfe des Elements
<sgmltag>table</sgmltag> auszeichnen. Eine Tabelle setzt
sich aus einer oder mehreren Zeilen (<sgmltag>tr</sgmltag>)
zusammen, von denen jede mindestens eine Zelle
(<sgmltag>td</sgmltag>) 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 <sgmltag>p</sgmltag> zu umschlie�en.</para>
<example>
<title>Einfache Tabelle mit <sgmltag>table</sgmltag></title>
<para>F�gen Sie in eine der existierenden �bungsdateien folgendes ein:</para>
<programlisting><![CDATA[<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>]]></programlisting></example>
<para>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
<literal>colspan</literal> erreicht werden, indem man ihm
die Anzahl der zusammenzufassenden Spalten zuweist.
�hnliches gilt f�r die Zusammenfassung von Zeilen:
Hierf�r wird dem Attribut <literal>rowspan</literal>
die Anzahl der zusammenzufassenden Zeilen zugewiesen.</para>
<example>
<title>Anwendung des Attributes <literal>rowspan</literal></title>
<programlisting><![CDATA[<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>]]></programlisting>
</example>
<example>
<title>Anwendung des Attributes <literal>colspan</literal></title>
<programlisting><![CDATA[<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>]]></programlisting>
</example>
<example>
<title>Gemeinsame Anwendung der Attrbute <literal>rowspan</literal> und
<literal>colspan</literal></title>
<programlisting><![CDATA[<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>]]></programlisting>
</example>
</sect3>
</sect2>
<sect2>
<title>Flu�elemente</title>
<sect3>
<title>Hervorheben von Information</title>
<para>Sollen sich bestimmte Informationen von anderen optisch
abheben, kann dies mit den HTML-Tags
<sgmltag>strong</sgmltag> und <sgmltag>em</sgmltag> erreicht
werden. <sgmltag>strong</sgmltag> stellt dabei eine
st�rkere Hervorhebung als <sgmltag>em</sgmltag> dar,
wobei mit <sgmltag>strong</sgmltag> ausgezeichnete Elemente
fett und mit <sgmltag>em</sgmltag> ausgezeichnete Elemente
kursiv dargestellt werden. Allerdings ist diese Aussage
nicht verl��lich, da die Darstellung vom Browser
abh�ngig ist.</para>
<example>
<title>Text mit <sgmltag>em</sgmltag> und <sgmltag>strong</sgmltag>
hervorheben</title>
<programlisting><![CDATA[<p><em>Dieses</em> Wort ist hervorgehoben,
w�hrend <strong>dieses noch st�rker hervorgehoben ist.</p>]]></programlisting>
</example>
</sect3>
<sect3>
<!--? Was ist typografisch richtig: schr�g oder kursiv?
Oliver Fischer -->
<title>Fett- und Schr�gschrift</title>
<para>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
<sgmltag>b</sgmltag> eingefa�te Inhalte werden fett
und mit <sgmltag>i</sgmltag> eingefa�te kursiv
dargestellt.</para>
<example>
<title>Text mit <sgmltag>b</sgmltag> und <sgmltag>i</sgmltag>
formatieren</title>
<programlisting><![CDATA[<p><b>Dieses</b> Wort wird fett dargestellt,
w�hrend <i>dieses</i> kursiv dargestellt wird.</p>]]></programlisting>
</example>
</sect3>
<sect3>
<title>Nicht-proportionale Schrift f�r Texte</title>
<para>Der Tag <sgmltag>tt</sgmltag> erlaubt es,
Text in einer schreibmaschinen�hnlichen
Schrift darzustellen.</para>
<example>
<title>Nicht-proportionale Schrift mit
<sgmltag>tt</sgmltag></title>
<programlisting><![CDATA[<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>]]></programlisting>
</example>
</sect3>
<sect3>
<title>�nderung der Schriftgr��e</title>
<para>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:</para>
<orderedlist>
<listitem>
<para>Mittels der Tags <sgmltag>big</sgmltag> und
<sgmltag>small</sgmltag> kann die
Darstellungsgr��e des eingeschlossenen Textes
vergr��ert respektive verkleinert werden.
HTML erlaubt es zudem, diese Tags zu verschachteln, so
dass auch <literal><big><big>Das ist
wesentlich
gr��er.</big></big></literal>
geschrieben werden kann.</para>
</listitem>
<listitem>
<para>Das gleiche Ergebnis kann �ber die Zuweisung der
Werte <literal>1</literal> und <literal>-1</literal> an
das Attribut <sgmltag role="attribute">size</sgmltag>
des Tags <sgmltag>font</sgmltag> erreicht werden. Diese
Vorgehensweise sollte allerdings als veraltet betrachtet
werden, da der Einsatz eines CSS hierf�r die bessere
L�sung darstellt.</para>
</listitem>
<listitem>
<para>�ber die Zuweisung von absoluten Werten im Bereich
von <literal>1</literal> bis <literal>7</literal> an das
Attribut <literal>size</literal> des Tags
<sgmltag>font</sgmltag> <footnote>
<para>Der Standardwert f�r <literal>size</literal> ist
<literal>3</literal>.</para></footnote>. Diese
Herangehensweise ist ebenfalls veraltet und sollte nicht
mehr angewandt werden.</para>
</listitem>
</orderedlist>
<example>
<title>Schriftgr��e �ndern mit
<sgmltag>big</sgmltag>, <sgmltag>small</sgmltag> und
<sgmltag>font</sgmltag></title>
<para>Die folgenden HTML-Schnipsel bewirken alle das gleiche:</para>
<programlisting><![CDATA[<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>]]></programlisting>
</example>
</sect3>
</sect2>
<sect2 id="links">
<title>Links</title>
<note>
<para>Bei Links handelt es sich ebenfalls Flu�elemente.</para>
</note>
<sect3>
<title>Auf andere Dokumente im WWW verweisen</title>
<para>Um auf ein anderes Dokument im WWW zu verweisen,
m�ssen Sie die URL dieses Dokuments kennen.</para>
<para>Links auf andere Dokumente im WWW werden in HTML durch
den Tag <sgmltag>a</sgmltag> und dessen Attribute <sgmltag
role="attribute">href</sgmltag>, 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.</para>
<example>
<title><literal><a href="..."></literal> benutzen</title>
<programlisting><![CDATA[<p>Weitere Informationen stehen auf der
<a href="http://www.FreeBSD.org/">FreeBSD-Webseite</a> zur Verf�gung.</p>]]></programlisting>
</example>
<para>Beim Aufruf dieses Links wird das referenzierte Dokument vom
Browser geladen und mit dessen Seitenanfang dargestellt.</para>
</sect3>
<sect3>
<title>Auf bestimmte Dokumentenabschnitte verweisen</title>
<para>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 <quote>Ankern</quote>
markiert werden. Diese Anker k�nnen ebenfalls mit Hilfe des
Tags <sgmltag>a</sgmltag> gesetzt werden, nur das anstelle
von <sgmltag role="attribute">href</sgmltag> das Attribut
<sgmltag role="attribute">name</sgmltag> gesetzt werden
muss.</para>
<example>
<title>Anwendung von <literal><a name="..."></literal></title>
<programlisting><![CDATA[<p><a name="absatz1">Auf</a> diesen Absatz kann mit
Hilfe seines Namens (<tt>absatz1</tt>) verwiesen werden.</p>]]></programlisting>
</example>
<para>Um auf einen so gekennzeichneten Abschnitt zu verweisen,
muss die URL des Dokumentes um das Zeichen
<literal>#</literal> und den Namen des Zielankers erweitert
werden.</para>
<example>
<title>Auf einen Abschnitt eines anderen Dokumentes
verweisen</title>
<para>F�r dieses Beispiel wird davon ausgegangen, dass der mit
<literal>absatz1</literal> gekennzeichnete Absatz sich in
der HTML-Datei <filename>foo.html</filename>
befindet.</para>
<programlisting><![CDATA[<p>Weitere Informationen k�nnen im
<a href="foo.html#absatz1">ersten Absatz</a> der Datei
<tt>foo.html</tt> gefunden werden.</p>]]></programlisting>
</example>
</sect3>
</sect2>
</sect1>
<sect1 id="sgml-markup-docbook">
<title>Die DocBook DTD</title>
<para>DocBook wurde urspr�glich von HaL Computer Systems and
O'Reilly & Associates als DTD f�r das Erstellen von
technischen Dokumenten entwickelt
<footnote><para>Einen kurzen historischen Abriss finden Sie unter
<ulink
url="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.</para>
</footnote>.
Seit 1998 wird es vom <ulink
url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
DocBook Technical Committee</ulink> 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.</para>
<note>
<title>Formelle und informelle Elemente</title>
<para>Einige Elemente der DocBook DTD sind in zwei Varianten
vorhanden: <emphasis>formell</emphasis> und
<emphasis>informell</emphasis>. �blicherweise besitzt die
formelle Variante einen Titel, dem der eigentliche
Elementeninhalt folgt. Die informelle Variante hingegen hat
keinen Titel.</para>
</note>
<para>Die DocBook DTD ist in der Ports-Sammlung im Port <filename
role="package">textproc/docbook</filename> enthalten und wird
bei der Installation des Metaports <filename
role="package">textproc/docproj</filename> automatisch
mitinstalliert.</para>
<sect2>
<title>Die FreeBSD-Erweiterungen</title>
<para>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.</para>
<para>Wenn nachfolgend im Text der Begriff
<quote>DocBook</quote> verwendet wird, ist damit die durch das
FDP erweiterte Version der DocBook DTD gemeint.</para>
<note>
<para>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 &a.doceng; Verbindung aufgenommen
werden.</para>
</note>
<para>Zum jetzigen Zeitpunkt sind die FreeBSD-Erweiterungen
nicht Bestandteil der Ports-Sammlung. Sie werden im
&os;-Subversion-Repository (<ulink
url="http://svnweb.FreeBSD.org/doc/head/share/sgml/freebsd.dtd">head/share/sgml/freebsd.dtd</ulink>)
verwaltet.</para>
</sect2>
<sect2>
<title>Formelle �ffentliche Bezeichner</title>
<para>In �bereinstimmung mir der DocBook-Richtlinie zur
Erstellung von Bezeichnern f�r DocBook-Erweiterungen lautet
der Bezeichner der erweiterten FreeBSD-Variante:</para>
<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
</sect2>
<sect2 id="docbookstructure">
<title>Die Struktur von DocBook-Dokumenten</title>
<para>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 <sgmltag>chapter</sgmltag>-Elemente strukturiert
wird. Sollte das noch nicht ausreichend sein, k�nnen die
einzelnen Kapitel eines Buches mit Hilfe des Elementes
<sgmltag>part</sgmltag> in Teile aufgespalten werden. Das
Handbuch ist beispielsweise auf diese Weise aufgebaut.</para>
<para>Kapitel (<sgmltag>chapter</sgmltag>) k�nnen weiterhin in
Unterkapitel unterteilt werden. Diese werden durch die
Elemente <sgmltag>sect1</sgmltag> ausgezeichnet. Soll ein
Unterkapitel selbst weitere Unterkapitel enthalten, kann das
�ber das Element <sgmltag>sect2</sgmltag> geschehen. Diese
Unterteilung kann bis zur Tiefe von f�nf Unterkapiteln –
�ber die Elemente <sgmltag>sect3</sgmltag>,
<sgmltag>sect4</sgmltag> und <sgmltag>sect5</sgmltag> –
fortgef�hrt werden. Der eigentliche Inhalt, um den es ja in
dem Artikel oder Buch geht, wird unterhalb der hier genannten
Elemente eingef�gt.</para>
<para>Vom Aufbau her ist ein Artikel ist einfacher strukturiert
als ein Buch. So kann ein Artikel beispielsweise keine Kapitel
(<sgmltag>chapter</sgmltag>) enthalten. Stattdessen kann der
Inhalt eines Artikels nur durch die schon bekannten
<sgmltag>sect<replaceable>N</replaceable></sgmltag>-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.</para>
<para>Alle <ulink url="&url.base;/de/docs.html">Tutorien von
FreeBSD</ulink> sind als Artikel verfa�t, w�hrend
hingegen die <ulink
url="&url.books.faq;/index.html">FreeBSD-FAQ</ulink> und das <ulink
url="&url.books.handbook;/index.html">FreeBSD-Handbuch</ulink> als
B�cher verfa�t wurden.</para>
<sect3>
<title>B�cher schreiben</title>
<para>Der Inhalt eines Buches wird in einem
<sgmltag>book</sgmltag>-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
<sgmltag>bookinfo</sgmltag>-Element abgelegt werden.</para>
<example>
<title>Buchvorlage <sgmltag>book</sgmltag> mit
<sgmltag>bookinfo</sgmltag></title>
<!-- Can't put this in a marked section because of the
replaceable elements -->
<programlisting><book>
<bookinfo>
<title><replaceable>Titel</replaceable></title>
<author>
<firstname><replaceable>Vorname</replaceable></firstname>
<surname><replaceable>Nachname</replaceable></surname>
<affiliation>
<address><email><replaceable>E-Mail-Adresse</replaceable></email></address>
</affiliation>
</author>
<copyright>
<year><replaceable>1998</replaceable></year>
<holder role="mailto:<replaceable>E-Mail-Adresse</replaceable>"><replaceable>Vollst�ndiger Name</replaceable></holder>
</copyright>
<releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para><replaceable>Kurze Zusammenfassung des Buchinhaltes.</replaceable></para>
</abstract>
</bookinfo>
…
</book></programlisting>
</example>
</sect3>
<sect3>
<title>Artikel schreiben</title>
<para>Der Inhalt eines Artikels wird in einem
<sgmltag>article</sgmltag>-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
<sgmltag>articleinfo</sgmltag>-Element abgelegt
werden.</para>
<example>
<title>Artikelvorlage <sgmltag>article</sgmltag> mit
<sgmltag>articleinfo</sgmltag></title>
<!-- Can't put this in a marked section because of the
replaceable elements -->
<programlisting><article>
<articleinfo>
<title><replaceable>Titel</replaceable></title>
<author>
<firstname><replaceable>Vorname</replaceable></firstname>
<surname><replaceable>Nachname</replaceable></surname>
<affiliation>
<address><email><replaceable>E-Mail-Adresse</replaceable></email></address>
</affiliation>
</author>
<copyright>
<year><replaceable>1998</replaceable></year>
<holder role="mailto:<replaceable>E-Mail-Adresse</replaceable>"><replaceable>Vollst�ndiger Name</replaceable></holder>
</copyright>
<releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para><replaceable>Kurze Zusammenfassung des Artikelinhalts.</replaceable></para>
</abstract>
</articleinfo>
…
</article></programlisting>
</example>
</sect3>
<sect3>
<title>Kapitel</title>
<para>Kapitel werden mit dem
<sgmltag>chapter</sgmltag>-Element angelegt und m�ssen ein
<sgmltag>title</sgmltag>-Element enthalten. Verwendet werden
k�nnen sie nur in B�chern.</para>
<example>
<title>Ein einfaches Kapitel</title>
<programlisting><![CDATA[<chapter>
<title>Kapitel�berschrift</title>
…
</chapter>]]></programlisting>
</example>
<para>Kapitel k�nnen nicht leer sein. Nebem einem
<sgmltag>title</sgmltag>-Element m�ssen sie weiteren Inhalt
beinhalten. Falls ein leeres Kapitel ben�tig wird, kann dies
durch das Einf�gen eines leeren Absatzes
(<sgmltag>para</sgmltag>) erreicht werden.</para>
<example>
<title>Ein leeres Kapitel</title>
<programlisting><![CDATA[<chapter>
<title>Das ist ein leeres Kapitel</title>
<para></para>
</chapter>]]></programlisting>
</example>
</sect3>
<sect3 id="unterkapitel">
<title>Unterkapitel</title>
<!-- Bei der Uebersetzung dieser Stelle bin ich
bewusst vom Original abgewichen, da ich die
Begriffe Kapitel und Kapitel anstatt
Kapitel und Abschnitt benutze. Eine
originalgetreue Uebersetzung wuerde somit an dieser
Stelle nur zu Verwirrung fuehren.
Oliver Fischer, 14.04.2004 -->
<para>B�cher werden auf der obersten Gliederungsebene
durch <sgmltag>chapter</sgmltag>-Elemente in Kapitel
unterteilt. Eine weitergehende Untergliederung kann durch
das Anlegen von Unterkapiteln erreicht werden. Im Gegensatz
zu Kapiteln, die durch <sgmltag>chapter</sgmltag>-Elemente
ausgezeichnet werden, erfolgt die Auszeichnung von
Unterkapitel mit dem Element
<sgmltag>sect<replaceable>n</replaceable></sgmltag>. Das
<replaceable>n</replaceable> in Elementnamen trifft eine
Aussage �ber die Gliederungstiefe, auf der sich das
Unterkapitel befindet. Ein <sgmltag>sect1</sgmltag>-Element
kann mehrere Elemente vom Typ <sgmltag>sect2</sgmltag>
enthalten, die die Unterkapitel der
n�chsten Gliederungsebene darstellen.
<sgmltag>sect5</sgmltag> ist das letzte Element, das auf
diese Art zur Gliederung eingesetzt werden kann.</para>
<example>
<title>Unterkapitel</title>
<programlisting><![CDATA[<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>]]></programlisting>
</example>
<note>
<para>Die Unterkapitel dieses Beispiels wurden zu
Demonstrationszwecken manuell durchnummeriert. In
<quote>normalen</quote> Dokumenten wird diese Aufgabe von
den Stylesheets �bernommen.</para>
</note>
</sect3>
<sect3>
<title>B�cher mittels <sgmltag>part</sgmltag>
unterteilen</title>
<para>In den F�llen, in denen die Unteilung eines Buches in
Kapitel nicht ausreichend ist, k�nnen mehrere
Kapitel mit dem Element <sgmltag>part</sgmltag> zu
einem Teil zusammengefasst werden.</para>
<programlisting><![CDATA[<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>]]></programlisting>
</sect3>
</sect2>
<sect2>
<title>Blockelemente</title>
<sect3>
<title>Abs�tze</title>
<para>DocBook kennt drei Arten von Abs�tzen: Abs�tze
mit �berschrift (<sgmltag>formalpara</sgmltag>),
normale Abs�tze (<sgmltag>para</sgmltag>) und einfache
Abs�tze (<sgmltag>simpara</sgmltag>).</para>
<para>Normale Abs�tze und einfache Abs�tze
unterscheiden sich dadurch, dass innerhalb von
<sgmltag>para</sgmltag> Blockelemente erlaubt sind,
innerhalb von <sgmltag>simpara</sgmltag> hingegen nicht. Es
ist empfehlenswert, <sgmltag>para</sgmltag> den Vorzug
zu geben.</para>
<example>
<title>Absatz mit <sgmltag>para</sgmltag></title>
<programlisting><![CDATA[<para>Das ist ein Absatz. Abs�tze k�nnen fast jedes andere
Element aufnehmen.</para>]]></programlisting>
<para>Darstellung:</para>
<para>Das ist ein Absatz. Abs�tze k�nnen fast jedes andere
Element aufnehmen.</para>
</example>
</sect3>
<sect3>
<title>Blockzitate</title>
<para>Blockzitate sind textlich umfangreichere Zitate aus
einem anderen Text, die nicht innerhalb des aktuellen
Absatzes angezeigt werden sollen. Wahlweise k�nnen
Blockzitate eine �berschrift haben und die Zitatquelle
nennen.</para>
<example>
<title><sgmltag>blockquote</sgmltag></title>
<programlisting><![CDATA[<para>Ein Auszug aus dem Grundgesetz:</para>
<blockquote>
<title>Menschenw�rde; Grundrechtsbindung der staatlichen Gewalt</title>
<attribution>Aus dem Grundgesetz</attribution>
<orderedlist>
<listitem>
<para>Die W�rde des Menschen ist unantastbar. Sie zu achten
und zu sch�tzen ist Verpflichtung aller staatlichen
Gewalten.</para>
</listitem>
<listitem>
<para>Das Deutsche Volk bekennt sich darum zu unverletzlichen
und unver�u�erlichen Menschenrechten als Grundlage jeder
menschlichen Gemeinschaft, des Friedens und der
Gerechtigkeit in der Welt.</para>
</listitem>
<listitem>
<para>Die nachfolgenden Grundrechte binden Gesetzgebung,
vollziehende Gewalt und Rechtsprechung als
unmittelbar geltendes Recht.</para>
</listitem>
</orderedlist>
</blockquote>]]></programlisting>
<para>Darstellung:</para>
<blockquote>
<title>Menschenw�rde; Grundrechtsbindung der
staatlichen Gewalt</title>
<attribution>Aus dem Grundgesetz</attribution>
<orderedlist>
<listitem>
<para>Die W�rde des Menschen ist unantastbar. Sie
zu achten und zu sch�tzen ist Verpflichtung
aller staatlichen Gewalten.</para>
</listitem>
<listitem>
<para>Das Deutsche Volk bekennt sich darum zu
unverletzlichen und unver�u�erlichen
Menschenrechten als Grundlage jeder menschlichen
Gemeinschaft, des Friedens und der Gerechtigkeit in
der Welt.</para>
</listitem>
<listitem>
<para>Die nachfolgenden Grundrechte binden
Gesetzgebung, vollziehende Gewalt und Rechtsprechung
als unmittelbar geltendes Recht.</para>
</listitem>
</orderedlist>
</blockquote>
</example>
</sect3>
<sect3>
<title>Tipps, Anmerkungen, Warnungen, wichtige Informationen
und Randbemerkungen</title>
<para>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 <sgmltag>tip</sgmltag>
(f�r Tipps), <sgmltag>note</sgmltag> (f�r
Anmerkungen), <sgmltag>warning</sgmltag> (f�r
Warnungen), <sgmltag>caution</sgmltag> (f�r besonders
ernstzunehmende Warnungen) und <sgmltag>important</sgmltag>
(f�r wichtige Anmerkungen) ausgezeichnet werden. Trifft
keines dieser Element f�r die auszuzeichnende Stelle
zu, sollte diese mit dem Element <sgmltag>sidebar</sgmltag>
ausgezeichnet werden.</para>
<para>Da die richtige Einordnung einer auszuzeichnenden
Textstelle nicht immer leicht zu treffen ist, werden in der
DocBook-Dokumentation folgende Empfehlungen gegeben:</para>
<itemizedlist>
<listitem>
<para>Eine Anmerkung (<sgmltag>note</sgmltag>) ist eine
Information, die von jedem Leser beachtet werden
sollte.</para>
</listitem>
<listitem>
<para>Eine wichtige Anmerkung
(<sgmltag>important</sgmltag>) eine Variation einer
Anmerkung.</para>
</listitem>
<listitem>
<para>Eine Warnung (<sgmltag>warning</sgmltag>)
betrifft einen m�glichen Hardwareschaden
oder weist auf eine Gefahr f�r Leib und Leben
hin.</para>
</listitem>
<listitem>
<para>Eine besonders ernstzunehmende Warnung
(<sgmltag>caution</sgmltag>) betrifft einen m�glichen
Datenverlust oder Softwareschaden.</para>
</listitem>
</itemizedlist>
<example>
<title><sgmltag>warning</sgmltag></title>
<programlisting><![CDATA[<warning>
<para>Wenn Sie FreeBSD auf Ihrer Festplatte installieren,
kann es sein, da&szlig; Sie Windows nie mehr benutzen wollen.</para>
</warning>]]></programlisting>
</example>
<para>Eine Warnung wird wie folgt dargestellt:</para>
<warning>
<para>Wenn Sie FreeBSD auf Ihrer Festplatte installieren,
kann es sein, dass Sie Windows nie mehr benutzen wollen.</para>
</warning>
</sect3>
<sect3>
<title>Listen und Handlungsanweisungen</title>
<para>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 <sgmltag>itemizedlist</sgmltag>,
<sgmltag>orderedlist</sgmltag> und
<sgmltag>procedure</sgmltag> zur Verf�gung.<footnote>
<para>DocBook kennt noch andere Elemente f�r die
Auszeichnung von Listen, die an dieser Stelle jedoch
nicht behandelt werden.</para>
</footnote>.</para>
<para><sgmltag>itemizedlist</sgmltag> und
<sgmltag>orderedlist</sgmltag> �hneln sehr stark ihren
HTML-Gegenst�cken <sgmltag>ul</sgmltag> und
<sgmltag>ol</sgmltag>. Beide Listenarten m�ssen
mindestens ein Element <sgmltag>listitem</sgmltag>
enthalten. Das <sgmltag>listitem</sgmltag> Element
muss mindestens ein weiteres Blockelement
enthalten.</para>
<para><sgmltag>procedure</sgmltag> unterscheidet sich ein
wenig von den vorhergehenden. Es enth�lt
<sgmltag>step</sgmltag>-Elemente, die wiederum
<sgmltag>step</sgmltag>- oder
<sgmltag>substel</sgmltag>-Elemente enthalten k�nnen.
Ein <sgmltag>step</sgmltag>-Element kann nur Blockelemente
aufnehmen.</para>
<example>
<title><sgmltag>itemizedlist</sgmltag>,
<sgmltag>orderedlist</sgmltag> und
<sgmltag>procedure</sgmltag></title>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<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>
</example>
<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>
</sect3>
<sect3>
<title>Dateiinhalte auszeichnen</title>
<para>Technische Dokumente enthalten oft auch
Konfigurationsbeispiele oder Quellcodeschnipsel. Zur
Auszeichnung dieser Inhalte, stellt Docbook das Element
<sgmltag>programmlisting</sgmltag> zur Verf�gung. Im
Gegensatz zu anderen DocBook-Elementen wird der
Elementinhalt von <sgmltag>programmlisting</sgmltag>
<emphasis>nicht</emphasis> normalisiert, das hei�t,
dass alle Leerzeichen, Tabulatoren und
Zeilenumbr�che unver�ndert �bernommen werden.
Aus diesem Grund ist es unter anderem wichtig, dass
sich der �ffende Tag in der selben Zeile wie der Anfang
des darzustellenden Textes befindet. Gleiches gilt f�r
den schlie�enden Tag: Er muss sich am Ende der
letzten Zeile befinden. Wird das nicht beachtet, kann es
sein, dass unerwartete Leerzeichen und Leerzeilen in
der Ausgabe auftauchen.</para>
<example>
<title><sgmltag>programlisting</sgmltag></title>
<programlisting><![CDATA[<para>Am Ende sollte Ihr Programm wie folgt
aussehen:</para>
<programlisting>#include &lt;stdio.h&gt;
int
main(void)
{
printf("Hallo Welt!\n");
}</programlisting>]]></programlisting>
<para>Die spitzen Klammern der
<literal>#include</literal>-Anweisung k�nnen nicht direkt
verwendet werden, sondern m�ssen �ber ihre Entit�ten
eingebunden werden.</para>
<para>Darstellung:</para>
<para>Am Ende sollte Ihr Programm wie folgt aussehen:</para>
<programlisting>#include <stdio.h>
int
main(void)
{
printf("Hallo Welt!\n");
}</programlisting>
</example>
</sect3>
<sect3>
<title>Textanmerkungen</title>
<para>Textanmerkungen<footnote><para>
auf Englisch:
<foreignphrase>callout</foreignphrase></para></footnote>
sind ein Mechanismus, um auf bestimmte Stellen in einem
vorhergehenden Beispiel oder Text zu verweisen.</para>
<para>Um solche Verweise anzulegen, m�ssen die betreffenden
Stellen in den Beispielen
(<sgmltag>programlisting</sgmltag>,
<sgmltag>literallayout</sgmltag>, …) mit
<sgmltag>co</sgmltag>-Elementen markiert werden, wobei jedes
Element ein eindeutiges <literal>id</literal>-Attribut
besitzen muss. Anschlie�end sollte ein
<sgmltag>calloutlist</sgmltag>-Element eingef�gt werden,
dessen Elemente sich auf die <sgmltag>co</sgmltag>-Elemente
des Beispiels beziehen und die jeweiligen Anmerkungen
enthalten.</para>
<example>
<title>Das <sgmltag>co</sgmltag>- und das
<sgmltag>calloutlist</sgmltag>-Element</title>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<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>
</example>
</sect3>
<sect3>
<title>Tabellen</title>
<para>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.</para>
<para>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
<sgmltag>table</sgmltag>-Element. Dieses Element selbst
beinhaltet mindestens ein Element <sgmltag>tgroup</sgmltag>,
das �ber ein Attribut die Spaltenanzahl der Tabelle
bestimmt. Innerhalb des Elementes <sgmltag>tgroup</sgmltag>
kann sich ein Element <sgmltag>thead</sgmltag> mit den
Spalten�berschriften und ein Element
<sgmltag>tbody</sgmltag> mit dem eigentlichen Tabelleninhalt
befinden. Beide Elemente beinhalten
<sgmltag>row</sgmltag>-Elemente, die wiederum
<sgmltag>entry</sgmltag>-Elemente beinhalten. Jedes
<sgmltag>entry</sgmltag>-Element stellt eine einzelne
Tabellenzelle dar.</para>
<example>
<title>Tabellen mittels <sgmltag>informaltable</sgmltag>
auszeichnen</title>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<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>
</example>
<para>Verwenden Sie stets das Attribut <literal>pgwide</literal>
mit dem Wert <literal>1</literal>, wenn Sie das Element
<sgmltag>informaltable</sgmltag> benutzen. Ein Bug des
Internet Explorers verhindert ansonsten die korrekte
Darstellung dieser Tabellen.</para>
<para>Soll die Tabelle keinen Rand haben, kann das Attribut
<literal>frame</literal> mit dem Wert
<literal>none</literal> dem Element
<sgmltag>informaltable</sgmltag> hinzugef�gt werden
(<literal><informaltable frame="none"></literal>)).</para>
<example>
<title>Tabelle mit Attribut
<literal>frame="none"</literal></title>
<para>Darstellung:</para>
<informaltable frame="none" 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>
</example>
</sect3>
<sect3>
<title>Beispiele f�r den Leser</title>
<para>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:</para>
<variablelist>
<varlistentry>
<term><sgmltag>screen</sgmltag></term>
<listitem>
<para>Gedacht zur Auszeichnung von Bildschirminhalten.
Im Unterschied zu anderen Elementen werden Leerzeichen
innerhalb des Elementes <sgmltag>screen</sgmltag>
unver�ndert �bernommen.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag>prompt</sgmltag>,
<literal>&prompt.root;</literal> und
<literal>&prompt.user;</literal></term>
<listitem>
<para>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
<sgmltag>prompt</sgmltag> ausgezeichnet werden.</para>
<para>Ein Spezialfall sind die beiden
Eingabeaufforderungen der Shell f�r normale
Benutzer und den Superuser <username>root</username>.
Jedesmal wenn auf eine von diesen beiden Nutzerrollen
hingewiesen werden soll, sollte entweder
<literal>&prompt.root;</literal> oder
<literal>&prompt.user;</literal> eingesetzt
werden. Beide Entit�ten k�nnen auch
au�erhalb von <sgmltag>screen</sgmltag>
verwendet werden.</para>
<note>
<para><literal>&prompt.root;</literal> und
<literal>&prompt.user;</literal> sind
FreeBSD-spezifische Erweiterungen der DocBook DTD
und nicht in der originalen DocBook DTD
enthalten.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><sgmltag>userinput</sgmltag></term>
<listitem>
<para>Das Element <sgmltag>userinput</sgmltag> ist
f�r die Auszeichnung von Benutzereingaben
gedacht.</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>
und <sgmltag>userinput</sgmltag></title>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<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>
</example>
<note>
<para>Obgleich der Inhalt der Datei
<filename>foo2</filename> in dem obigen Beispiel angezeigt
wird, sollte dieser nicht mit
<sgmltag>programlisting</sgmltag> ausgezeichnet werden.
Vielmehr sollte <sgmltag>programlisting</sgmltag> einzig
und allein f�r die Darstellung von Dateifragmenten
au�erhalb von Benutzeraktionen gew�hlt
werden.</para>
</note>
</sect3>
</sect2>
<sect2>
<title>Flu�elemente</title>
<sect3>
<title>Hervorhebungen</title>
<para>Wenn es darum geht bestimmte W�rter oder Textstellen
hervorzuheben, sollte daf�r das Element
<sgmltag>emphasis</sgmltag> verwendet werden. Das so
ausgezeichnete Text wird dann kursiv oder fett dargestellt;
im Falle einer Sprachausgabe w�rde es anders betont
werden.</para>
<para>Im Gegensatz zu den HTML mit seinen Elementen
<sgmltag>b</sgmltag> und <sgmltag>i</sgmltag>, kennt DocBook
keinen Weg, um diese Darstellung zu
�ndern<footnote><para>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.</para></footnote>. Handelt es sich bei
dem darzustellenden um eine wichtige Information, kann
alternativ <sgmltag>important</sgmltag> verwendet
werden.</para>
<example>
<title>Das Element <sgmltag>emphasis</sgmltag></title>
<programlisting><![CDATA[<para>FreeBSD ist zweifelslos <emphasis>das</emphasis> f�hrende
Unix-artige Bestriebssystem f�r die Intel-Plattform.</para>]]></programlisting>
<para>Darstellung:</para>
<para>FreeBSD ist zweifelslos <emphasis>das</emphasis> f�hrende
Unix-artige Bestriebssystem f�r die Intel-Plattform.</para>
</example>
</sect3>
<sect3>
<title>Zitate</title>
<para>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
<sgmltag>quote</sgmltag> ausgezeichnet werden. Innerhalb von
<sgmltag>quote</sgmltag> k�nnen die meisten der
normalerweise zur Verf�gung stehenden Elemente genutzt
werden.</para>
<example>
<title>Richtig zitieren</title>
<programlisting><![CDATA[<para>Es sollte immer sichergestellt werden, dass die Suche die Grenzen
zwischen <quote>lokaler und �ffentlicher Administration</quote>
(RFC 1535) einh�lt.</para>]]></programlisting>
<para>Darstellung:</para>
<para>Es sollte immer sichergestellt werden, das die Suche
die Grenzen zwischen <quote>lokaler und �ffentlicher
Administration</quote> (RFC 1535) einh�lt.</para>
</example>
</sect3>
<sect3>
<title>Tasten, Maustasten und Tastenkombinationen</title>
<para>Das Element <sgmltag>keycap</sgmltag> beschreibt
eine bestimmte Taste der Tastatur.
F�r die Auszeichnung von Maustasten
steht analog das Element <sgmltag>mousebutton</sgmltag> zur
Verf�gung. Mit Hilfe von <sgmltag>keycombo</sgmltag>
k�nnen beliebige Tasten- und Maustastenkombinationen
beschrieben werden.</para>
<para>Das Element <sgmltag>keycombo</sgmltag> besitzt ein
Attribut <literal>action</literal>, dem einer der Werte
<literal>click</literal>, <literal>double-click</literal>,
<literal>other</literal>, <literal>press</literal>,
<literal>seq</literal> oder <literal>simul</literal>
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
<sgmltag>keycombo</sgmltag> <quote>+</quote>-Zeichen
ein.</para>
<example>
<title>Tasten, Maustasten und Tastenkombinationen</title>
<para>Diese Eingaben zeichnen Sie wie folgt aus:</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<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>
</example>
</sect3>
<sect3>
<title>Anwendungen, Befehle, Optionen und Hilfeseiten</title>
<para>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<footnote><para>Der Befehl
<command>mozilla</command> startet das Programm
<application>mozilla</application>.</para>
</footnote>.</para>
<para>Desweiteren kann es auch vorkommen, dass die
von einem Programm (in einem bestimmten Fall)
akzeptierten Optionen genannt werden m�ssen.</para>
<para>Schlu�endlich ist es oft gew�nscht, zu einem
Befehl dessen Abschnitt der Manualseiten im
Unix-�blichen Stil <quote>Befehl(Zahl)</quote>
anzugeben.</para>
<para>Anwendungsnamen k�nnen mit <sgmltag>application</sgmltag>
ausgezeichnet werden.</para>
<para>Befehle k�nnen zusammen mit der betreffenden
Hilfeseite �ber das DocBook-Element
<sgmltag>citerefentry</sgmltag> ausgezeichnet werden.
<sgmltag>citerefentry</sgmltag> muss zwei weitere
Elemente enthalten: <sgmltag>refentrytitle</sgmltag>,
f�r den Befehlsnamen, und <sgmltag>manvolnum</sgmltag>,
f�r die Kategorie der Hilfeseite.</para>
<para>Diese Art auf Befehle zu verweisen kann sehr
erm�dent sein. Daher gibt es einen Satz von
<link linkend="sgml-primer-general-entities">Allgemeinen
Entit�ten</link>, der diese Arbeit erleichtert. Er
ist in der Datei
<filename>doc/share/sgml/man-refs.ent</filename> enhalten
und kann �ber den folgenden Bezeichner eingebunden
werden:</para>
<programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
<para>Jede Entit�t in dieser Datei ist wie folgt aufgebaut:
<literal>&man.<replaceable>Hilfeseite</replaceable>.<replaceable>Kategorie</replaceable>;</literal>.</para>
<para>Der Anfang eines Dokumentes, das diese Entit�ten
einbindet, k�nnte so aussehen:</para>
<programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man; … ]></programlisting>
<para>Um Befehle innerhalb des Flie�textes auszuzeichen,
kann das Element <sgmltag>command</sgmltag> genutzt werden.
Die Optionen eines Befehles k�nnen mit Hilfe von
<sgmltag>option</sgmltag> ausgezeichnet werden.</para>
<para>Wenn man sich mehrmals hintereinander auf den gleichen
Befehl bezieht, sollte man beim ersten Auftreten die Notation
<literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
verwenden. F�r alle folgenden Referenzen sollte hingegen
<sgmltag>command</sgmltag> verwendet werden. Dadurch
verbessert sich das Erscheinungsbild, insbesondere von HTML,
deutlich.</para>
<para>Die Unterscheidung zwischen <sgmltag>command</sgmltag>
und <sgmltag>application</sgmltag> kann schwer sein, und
manchmal ist die Entscheidung, welches Element das richtige
ist, nicht leicht. Das folgende Beispiel soll diese
Unterscheidung erleichtern.</para>
<example>
<title>Anwendungen, Befehle und Optionen</title>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<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; sowie &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>
</example>
<note>
<para>Die Schreibweise
<literal>&man.<replaceable>Hilfeseite</replaceable>.<replaceable>Kategorie</replaceable>;</literal>
ist leichter lesbar.</para>
</note>
</sect3>
<sect3>
<title>Dateien, Verzeichnisse und Erweiterungen</title>
<para>Immer wenn in einem Text der Name einer Datei, eines
Verzeichnisses oder eine Dateierweiterung vorkommt, sollte
die betreffende Stelle mit dem Element
<sgmltag>filename</sgmltag> ausgezeichnet werden.</para>
<example>
<title>Das Element <sgmltag>filename</sgmltag></title>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<para>Die SGML-Quellen des englischen Handbuches befinden
sich im Verzeichnis
<filename>/usr/doc/en/handbook/</filename>. In diesem
Verzeichnis befindet sich eine Datei
<filename>handbook.sgml</filename>. Desweiteren sollte
sich eine Datei mit dem Namen
<filename>Makefile</filename> zusammen mit mehreren
Dateien mit der Endung <filename>.ent</filename> in diesem
Verzeichnis befinden.</para>
</example>
</sect3>
<sect3>
<title>Portnamen</title>
<note>
<title>FreeBSD-Erweiterung</title>
<para>Die hier genannten Elemente sind Bestandteil der
FreeBSD-Erweiterung f�r DocBook und sind nicht in der
originalen DocBook DTD enthalten.</para>
</note>
<para>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
<sgmltag>filename</sgmltag> eingesetzt werden, dabei aber
dem Element das Attribut <literal>role</literal> mit dem
Wert <literal>package</literal> zugewiesen werden. Da die
Ports-Sammlung an jeder beliebigen Stelle im Dateisystem
installiert werden kann, sollte <sgmltag>filename</sgmltag>
nur die Kategorie und den Namen des Ports enthalten, aber
nicht das Verzeichnis
<filename>/usr/ports</filename>.</para>
<example>
<title>Portsnamen und das Element <sgmltag>filename</sgmltag></title>
<programlisting><![CDATA[<para>Wenn Sie Ihr Netz und dessen Datenverkehr analysieren
m�chten, dann installieren Sie bitte den Port <filename
role="package">net/ethereal</filename>.</para>]]></programlisting>
<para>Darstellung:</para>
<para>Wenn Sie Ihr Netz und dessen Datenverkehr analysieren
m�chten, dann installieren Sie bitte den Port <filename
role="package">net/ethereal</filename>.</para>
</example>
</sect3>
<sect3>
<title>Ger�tedateien unterhalb von
<filename>/dev</filename></title>
<note>
<title>FreeBSD-Erweiterung</title>
<para>Die hier genannten Elemente sind Bestandteil der
FreeBSD-Erweiterung f�r DocBook und sind nicht in der
originalen DocBook DTD enthalten.</para>
</note>
<para>Wird in einem Dokument Bezug auf Ger�tedateien
unterhalb von <filename class="directory">dev</filename>
genommen, dann gibt es zwei M�glichkeiten diese
auszuzeichnen. Zum einen kann man sich auf das Ger�t
beziehen, so wie es unter <filename>/dev</filename> 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 <sgmltag>devicename</sgmltag> genutzt
werden.</para>
<para>Allerdings besteht nicht immer diese
Wahlm�glichkeit. Einige Ger�te, wie zum Beispiel
Netzwerkkartenm haben keinen Eintrag unter
<filename>/dev</filename> oder werden anders
dargestellt.</para>
<example>
<title>Ger�tenamen per <sgmltag>devicename</sgmltag>
auszeichnen</title>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<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>
</example>
</sect3>
<sect3>
<title>Rechner, Domains, IP-Adressen und mehr</title>
<note>
<title>FreeBSD-Erweiterung</title>
<para>Die hier genannten Elemente sind Bestandteil der
FreeBSD-Erweiterung f�r DocBook und sind nicht in der
originalen DocBook DTD enthalten.</para>
</note>
<para>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 <sgmltag>hostid</sgmltag> benutzen. �ber das
Attribut <literal>role</literal> wird die Art des Bezeichners
genauer bestimmt.</para>
<variablelist>
<varlistentry>
<term>Kein Rollenattribut oder
<literal>role="hostname"</literal></term>
<listitem>
<para>Ohne Rollenattribut stellt der umschlossene Text
einen normlen Rechnernamen wie
<literal>freefall</literal> oder
<literal>wcarchive</literal> dar. Wenn es
gew�nscht ist, kann mittels
<literal>role="hostname"</literal> explizit angegeben
werden, dass es sich um einen Rechnernamen
handelt.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="domainname"</literal></term>
<listitem>
<para>Ein Domainname wie <literal>FreeBSD.org</literal>
oder <literal>ngo.org.uk</literal>. Er enth�lt keinen
Rechnernamen.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="fqdn"</literal></term>
<listitem>
<para>Vollqualifizierter Domainname wie
<literal>www.FreeBSD.org</literal>. Enth�lt sowohl
einen Domainnamen als auch einen Rechnernamen.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="ipaddr"</literal></term>
<listitem>
<para>Eine IP-Adresse, meistens als durch Doppelpunkte
getrenntes Tupel von vier Zahlen dargestellt.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="ip6addr"</literal></term>
<listitem>
<para>Eine IPv6-Adresse.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="netmask"</literal></term>
<listitem>
<para>Eine Netzwerkmaske, dargestellt als ein durch
Doppelpunkte getrenntes Vierzahlentupel, einer Hexzahl
oder als ein <literal>/</literal>, dem eine Zahl
folgt.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>role="mac"</literal></term>
<listitem>
<para>Eine MAC-Adresse, dargestellt durch zweistellige
Hexzahlen, die durch Doppelpunkte getrennt
sind.</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title><literal>role</literal> und
<sgmltag>hostid</sgmltag></title>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<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
verschieden Rechner, inklusive <hostid
role="fqdn">freefall.FreeBSD.org</hostid> und <hostid
role="fqdn">bento.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>
</example>
</sect3>
<sect3>
<title>Benutzernamen</title>
<note>
<title>FreeBSD-Erweiterung</title>
<para>Die hier genannten Elemente sind Bestandteil der
FreeBSD-Erweiterung f�r DocBook und sind nicht in der
originalen DocBook DTD enthalten.</para>
</note>
<para>Namen von Benutzern, wie
<literal>root</literal> oder <literal>bib</literal>,
k�nnen mit dem Element <sgmltag>username</sgmltag>
ausgezeichnet werden.</para>
<example>
<title>Das Element <sgmltag>username</sgmltag></title>
<programlisting><![CDATA[<para>F�r die meisten Administrationsaufgaben m�ssen
Sie als <username>root</username> angemeldet sein.</para>]]></programlisting>
<para>Darstellung:</para>
<para>F�r die meisten Administrationsaufgaben m�ssen Sie als
<username>root</username> angemeldet sein.</para>
</example>
</sect3>
<sect3>
<title>Beschreibung von <filename>Makefile</filename>s</title>
<note>
<title>FreeBSD-Erweiterung</title>
<para>Die hier genannten Elemente sind Bestandteil der
FreeBSD-Erweiterung f�r DocBook und sind nicht in der
originalen DocBook DTD enthalten.</para>
</note>
<para>Zur Beschreibung von Teilen einer Makedatei stehen die
beiden Elemente <sgmltag>marketarget</sgmltag> und
<sgmltag>makevar</sgmltag> zur Verf�gung.
<sgmltag>maketarget</sgmltag> bezeichnet ein Ziel eines
<filename>Makefile</filename>s, das als Parameter beim
Aufruf von <command>make</command> angegeben werden kann.
<sgmltag>makevar</sgmltag> hingegen bezeichnet eine
Variable, die entweder in einem
<filename>Makefile</filename> definiert oder
<command>make</command> auf der Befehlszeile �bergeben
werden kann, um so den Bauprozess zu beeinflussen.</para>
<example>
<title><sgmltag>maketarget</sgmltag> und
<sgmltag>makevar</sgmltag></title>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<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>
</example>
</sect3>
<sect3>
<title>Text buchstabengetreu �bernehmen</title>
<para>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.</para>
<para>In einigen F�llen ist zu diesem Zwecke
<sgmltag>programlisting</sgmltag> ausreichend, jedoch nicht
immer. So ist <sgmltag>programlisting</sgmltag> 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 <sgmltag>literal</sgmltag> zum Einsatz
kommen.</para>
<example>
<title><sgmltag>literal</sgmltag></title>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<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>
</example>
</sect3>
<sect3>
<title>Benutzerspezifische Eingaben darstellen</title>
<!--@todo Klingt ein wenig kompiliziert.
Oliver Fischer -->
<para>Es kommt oft vor, dass der Leser Beispiele,
Dateinamen oder Kommandozeilen ver�ndern muss.
F�r einen solchen Anwendungsfall
ist das Element <sgmltag>replaceable</sgmltag> gedacht. Es
kann <emphasis>innerhalb</emphasis> von anderen Elementen
genutzt werden, um die Teile auszuzeichnen, die es zu
ersetzen gilt.</para>
<example>
<title>Das Element <sgmltag>replaceable</sgmltag></title>
<programlisting><![CDATA[<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting>
<para>Darstellung:</para>
<informalexample>
<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
</informalexample>
<para>Dieses Beispiel zeigt, dass nur der Text mit
<sgmltag>replaceable</sgmltag> umschlossen werden soll,
den der Benutzer einzusetzen hat. S�mtlicher anderer
Text sollte wie �blich ausgezeichnet werden.</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Darstellung:</para>
<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>
</example>
</sect3>
<sect3>
<title>Fehlermeldungen des Systems darstellen</title>
<para>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
<sgmltag>errorname</sgmltag> vorgesehen.</para>
<example>
<title>Das Element <sgmltag>errorname</sgmltag></title>
<programlisting><![CDATA[ <screen><errorname>Panic: cannot mount root</errorname></screen> ]]></programlisting>
<para>Darstellung:</para>
<informalexample>
<screen><errorname>Panic: cannot mount root</errorname></screen>
</informalexample>
</example>
</sect3>
</sect2>
<sect2>
<title>Bilder und Grafiken</title>
<important>
<para>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.</para>
<para>F�r die Verwendung von Grafiken ist es notwendig,
den Port <filename
role="package">graphics/ImageMagick</filename>
zus�tzlich zu installieren, da er
<emphasis>nicht</emphasis> vom Port <filename
role="package">textproc/docproj</filename> mitinstalliert
wird.</para>
<para>Das beste Beispiel f�r den Einsatz von Grafiken ist
der unter
<filename>doc/en_US.ISO8859-1/articles/vm-design/</filename>
zu findene Artikel <quote>Design elements of the FreeBSD VM
system</quote>. 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.</para>
</important>
<sect3>
<title>Unterst�tze Grafikformate</title>
<para>Zur Zeit werden nur zwei Grafikformate unterst�tzt.
Welches von beiden Formaten zum Einsatz kommen sollte,
h�ngt von der Art der Grafik ab.</para>
<para>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 <filename>.eps</filename> 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 <filename>.png</filename> haben.</para>
<para>In das Subversion-Repository sollten <emphasis>nur</emphasis>
Grafiken in diesen beiden Formaten �bernommen
werden.</para>
<para>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. <emphasis>Deshalb sollte die gleiche Grafik niemals
in zwei unterschiedlichen Formaten in das CVS-Archiv
�bernommen werden</emphasis>.</para>
<important>
<para>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.</para>
</important>
</sect3>
<sect3>
<title>DocBook-Elemente f�r den Grafikeinsatz</title>
<para>Das Auszeichnen von Bildern mittels DocBook ist relativ
einfach. Zuerst wird ein
<sgmltag>mediaobject</sgmltag>-Element eingef�gt, das
als Container f�r medienspezifische Elemente fungieren
kann. F�r die Zwecke des FDPs sind das die Elemente
<sgmltag>imageobject</sgmltag> und
<sgmltag>textobject</sgmltag>.</para>
<para>In das <sgmltag>mediaobject</sgmltag>-Element sollten
ein Element vom Typ <sgmltag>imageobject</sgmltag> und zwei
<sgmltag>textobject</sgmltag>-Elemente eingef�gt
werden. Das <sgmltag>imageobject</sgmltag>-Element verweist
auf die eigentliche Grafikdatei. Dabei ist allerdings nur
der Dateipfad ohne Erweiterung anzugegeben. Die
<sgmltag>textobject</sgmltag>-Elemente werden daf�r
genutzt, Texte aufzunehmen, die dem Leser anstelle des
Bildes oder zusammen mit dem Bild angezeigt werden.</para>
<para>Dies kann unter zwei Umst�nden geschehen:</para>
<itemizedlist>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
</itemizedlist>
<para>Das folgende Beispiel soll das bisher geschriebene
illustrieren. Angenommen es liegt eine einzubindene Grafik
in der Datei <filename>bild1</filename> vor, die die
Darstellung eines As in einem Rechteck enth�lt. Die
ASCII-Alternative k�nnte so ausgezeichnet werden:</para>
<programlisting><mediaobject>
<imageobject>
<imagedata fileref="bild1"> <co id="co-image-ext"/>
</imageobject>
<textobject>
<literallayout class="monospaced">+ - - - - - - - - - - - - - - -+ <co id="co-image-literal"/>
| A |
+- - - - - - - - - - - - - - -+</literallayout>
</textobject>
<textobject>
<phrase>Ein Bild</phrase> <co id="co-image-phrase"/>
</textobject>
</mediaobject></programlisting>
<calloutlist>
<callout arearefs="co-image-ext">
<para>Innerhalb vom Element <sgmltag>imageobject</sgmltag>
befindet sich ein Element <sgmltag>imagedata</sgmltag>,
welches mit Hilfe des Attributes
<literal>fileref</literal> den Namen der Grafikdatei
(ohne Erweiterung) angibt. Die Bestimmung der
Dateierweiterung wird von den Stylesheets
�bernommen.</para>
</callout>
<callout arearefs="co-image-literal">
<para>Das erste <sgmltag>textobject</sgmltag>-Element
enth�lt ein <sgmltag>literallayout</sgmltag>-Element,
dessen Attribut <literal>class</literal> den Wert
<literal>monospaced</literal> 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
<quote>Textzeichenk�nste</quote> unter Beweis zu
stellen.</para>
<para>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.</para>
</callout>
<callout arearefs="co-image-phrase">
<para>Das zweite <sgmltag>textobject</sgmltag>-Element
sollte lediglich ein <sgmltag>phrase</sgmltag>-Element
enthalten. Wird das Dokument nach HTML konvertiert, wird
dessen Inhalt f�r das Attribut
<literal>alt</literal> des <sgmltag>img</sgmltag>-Tags
verwendet.</para>
</callout>
</calloutlist>
</sect3>
<sect3>
<title>Die <filename>Makefile</filename>-Eintr�ge</title>
<para>Alle in einem Dokument verwendeten Grafiken m�ssen in
dem zugeh�rigen Makefile in der Variable
<makevar>IMAGES</makevar> enthalten sein.
<makevar>IMAGES</makevar> sollte immer die Namen der
<emphasis>Quellgrafiken</emphasis> enthalten. Werden in
einem Dokument beispielsweise die drei Grafiken
<filename>bild1.eps</filename>,
<filename>bild2.png</filename> und
<filename>bild3.png</filename> referenziert, sollte das
<filename>Makefile</filename> die folgende Zeile
enthalten:</para>
<programlisting>…
IMAGES= bild1.eps bild2.png bild3.png
…</programlisting>
<para>Eine andere M�glichkeit w�re:</para>
<programlisting>…
IMAGES= bild1.eps
IMAGES+= bild2.png
IMAGES+= bild3.png
…</programlisting>
<para>Es kann nicht oft genug betont werden: Welche
Grafikdateien f�r das zu erzeugende Dokument ben�tigt
werden, wird von dem Makefiles bestimmt.
<makevar>IMAGES</makevar> darf nur die Originaldateien
enthalten.</para>
</sect3>
<sect3>
<title>Grafiken und Kapitel in Unterverzeichnissen</title>
<para>Wenn Sie Ihre Dokumentation in mehrere kleine
Dateien aufspalten (siehe
<xref linkend="sgml-primer-include-using-gen-entities"/>),
m�ssen Sie sorgf�ltig vorgehen.</para>
<para>Angenommen es handelt sich um ein Buch, dessen drei
Kapitel in separaten Verzeichnissen angelegt wurden
(<filename>kapitel1/kapitel.sgml</filename>,
<filename>kapitel2/kapitel.sgml</filename> und
<filename>kapitel3/kapitel.sgml</filename>). 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 <makevar>IMAGES</makevar> und
in den <sgmltag>imagedata</sgmltag>-Elementen immer auch den
Verzeichnisnamen mitenthalten.</para>
<para>Soll beispielsweise die Datei
<filename>kapitel1/bild1.png</filename> in das in
<filename>kapitel1/kapitel.sgml</filename> enthaltene
Kapitel eingebunden werden, sollte dies so erfolgen:</para>
<programlisting><mediaobject>
<imageobject>
<imagedata fileref="kapitel1/bild1"> <co id="co-image-dir"/>
</imageobject>
…
</mediaobject></programlisting>
<calloutlist>
<callout arearefs="co-image-dir">
<para><literal>fileref</literal> muss den
Datei- und den Verzeichnisnamen enthalten.</para>
</callout>
</calloutlist>
<para>Das <filename>Makefile</filename> muss dementsprechend
die Zeile
<programlisting>…
IMAGES= kapitel1/bild1.png
…</programlisting>
enthalten.</para>
<para>Wird dies beachtet, sollte es zu keinen Problemen
kommen.</para>
</sect3>
</sect2>
<sect2>
<title>Querverweise</title>
<note>
<para>Querverweise sind auch Flu�elemente.</para>
</note>
<sect3>
<title>Querverweise innerhalb eines Dokumentes</title>
<para>Um innerhalb eines Dokumentes Verweise anzulegen, muss
angegeben werden, von welcher Textstelle aus wohin verwiesen
werden soll.</para>
<para>Jedes DocBook-Element besitzt ein Attribut
<literal>id</literal>, �ber das seinem Element ein
eindeutiger Bezeichner zugewiesen werden kann.</para>
<!-- ?: Mit diesem Absatz bin ich gar nicht zu frieden! -->
<para>In den meisten F�llen werden Querverweise nur zu
Kapiteln gesetzt. Die <sgmltag>chaper</sgmltag>- und
<sgmltag>sect*</sgmltag>-Elemente sollten aus diesem Grunde
ein gesetztes <literal>id</literal>-Attribut
besitzen.</para>
<example>
<title><sgmltag>chapter</sgmltag> und <sgmltag>section</sgmltag>
mit dem Attribut <literal>id</literal></title>
<!--<title><literal>id on chapters and sections</literal></title>-->
<programlisting><![CDATA[<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>]]></programlisting>
</example>
<para>Als Wert f�r das Attribut <literal>id</literal>
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.</para>
<para>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 <sgmltag>anchor</sgmltag> mit gesetztem
Attribut <literal>id</literal> eingef�gt werden.
<sgmltag>anchor</sgmltag> kann selber keinen weiteren Inhalt
aufnehmen.</para>
<example>
<title>Querverweise und das Element
<sgmltag>anchor</sgmltag></title>
<programlisting><![CDATA[<para>Dieser Absatz enth�lt ein
<anchor id="absatz1"/>Ziel f�r Querverweise, was jedoch keine
Auswirkung auf dessen Darstellung hat.</para>]]></programlisting>
</example>
<para>Zum Anlegen des eigentlichen Querverweises selbst kann
eines der beiden Elemente <sgmltag>xref</sgmltag> oder
<sgmltag>link</sgmltag> genutzt werden. Beide besitzen das
Attribut <literal>linkend</literal>, dem der
<literal>id</literal>-Wert des Verweiszieles zugewiesen
wird. Ob sich das Ziel vor oder nach dem Verweis befindet,
spielt keine Rolle.</para>
<para><sgmltag>xref</sgmltag> und <sgmltag>link</sgmltag>
unterscheiden sich jedoch hinsichtlich der Art und Weise,
auf die der Text erzeugt wird, auf dem der Querverweis
liegt. Kommt <sgmltag>xref</sgmltag> zum Einsatz, hat der
Autor keine Kontrolle dar�ber – der Text wird
automatisch f�r ihn erzeugt.</para>
<example>
<title>Einsatz von <sgmltag>xref</sgmltag></title>
<!-- @todo Das englische Original sollte um
einen Link zu dem Beispiel erweitert werden. -->
<para>F�r dieses Beispiel wird davon ausgegangen, dass sich
folgendes Textfragment irgendwo innerhalb eines Dokumentes
auftaucht, dass das vorherige
<literal>id</literal>-Beispiel enth�lt.</para>
<programlisting><![CDATA[<para>Weitere Informationen gibt
es im <xref linkend="kapitel1"/>.</para>
<para>Genauere Informationen k�nnen im
<xref linkend="kapitel1-unterkapitel1"/> gefunden werden.</para>]]></programlisting>
<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.</para>
<blockquote>
<para>Weitere Informationen k�nnen in der
<emphasis>Einf�hrung</emphasis> gefunden
werden.</para>
<para>Genauere Informationen k�nnen im
<emphasis>Unterkapitel 1</emphasis> gefunden
werden.</para>
</blockquote>
</example>
<para>Der Text, auf dem der HTML-Link f�r den Querverweis
liegt, wurde von den Kapitel�berschriften
�bernommen.</para>
<note>
<para>Das bedeutet, dass es <emphasis>nicht
m�glich</emphasis> ist, mit der Hilfe von
<sgmltag>xref</sgmltag> einen Querverweis zu einer mit
<sgmltag>anchor</sgmltag> gekennzeichneten Stelle
anzulegen. Da <sgmltag>anchor</sgmltag> keinen Inhalt
aufnehmen kann, k�nnen die Stylesheets nicht
automatisch einen Text f�r den Verweis
erzeugen.</para>
</note>
<para>M�chte man selber den f�r den Verweis
benutzten Text bestimmen k�nnen, sollte das Element
<sgmltag>link</sgmltag> verwendet werden. Im Gegensatz zu
<sgmltag>xref</sgmltag> kann <sgmltag>link</sgmltag> Inhalt
aufnehmen, der dann f�r den Verweis verwendet
wird.</para>
<example>
<title><sgmltag>link</sgmltag> beutzen</title>
<para>F�r dieses Beispiel wird davon ausgegangen, dass
es sich in dem Dokument befindet, das auch
das <literal>id</literal>-Beispiel enth�lt.</para>
<programlisting><![CDATA[<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>]]></programlisting>
<para>Aus diesem SGML-Fragment w�rden die Stylesheets
folgendes generieren (der hervorgehobene Text deutet den
erzeugten Verweis an):</para>
<blockquote>
<para>Weitere Informationen k�nnen im <emphasis>ersten
Kapitel</emphasis> gefunden werden.</para>
<para>Genauere Informationen k�nnen in
<emphasis>diesem</emphasis> Kapitel gefunden
werden.</para>
</blockquote>
</example>
<note>
<para>Das letzte Beispiel ist schlecht. Es sollten niemals
W�rter wie <quote>dieses</quote> oder
<quote>hier</quote> 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.</para>
</note>
<note>
<para>Mit dem Element <sgmltag>link</sgmltag>
<emphasis>kann</emphasis> auf mit
<sgmltag>anchor</sgmltag> gekennzeichnete Stellen im
Dokument verwiesen werden, da der Inhalt von
<sgmltag>link</sgmltag> als Text f�r den Querverweise
genutzt wird.</para>
</note>
</sect3>
<sect3>
<title>Verweise auf Dokumente im WWW</title>
<para>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 <sgmltag>ulink</sgmltag> ausgezeichnet werden.
Mittels des Attributes <literal>url</literal> kann die
Adresse des Zieldokumentes angegeben werden. Bei der
Umformung des Quelldokumentes in die verschiedenen
Ausgabeformate wird der sich zwischen Start- und Endtag
befindliche Text f�r den Verweis �bernommen, den
der Leser aufrufen kann.</para>
<example>
<title>Verweise mit <sgmltag>ulink</sgmltag></title>
<!-- @todo Welchen Fall erforder anstatt? -->
<programlisting><![CDATA[<para>Nat�rlich ist es m�glich, anstatt diesen Text
weiterzulesen, sofort die
<ulink url="&url.base;/de/index.html">FreeBSD-Homepage</ulink>
aufzurufen.<para>]]></programlisting>
<para>Darstellung:</para>
<para>Nat�rlich ist es m�glich, anstatt diesen Text
weiterzulesen, sofort die <ulink
url="&url.base;/de/index.html">FreeBSD-Homepage</ulink>
aufzurufen.</para>
</example>
</sect3>
</sect2>
</sect1>
</chapter>