os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
doc/de_DE.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
Gabor Kovesdan 9c243757ef - XML declarations should use IANA encoding names 
Pointed out by:	hrs
2012-09-14 17:47:48 +00:00

2992 lines
108 KiB
XML
Raw Blame History

<?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 &ndash; 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>&lt;html>
&lt;head>
&lt;title><replaceable>Der Dokumententitel</replaceable>&lt;/title>
&lt;/head>
&lt;body>
&hellip;
&lt;/body>
&lt;/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>&hellip;</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:
&lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;
Kommentare und Anmerkungen sind willkommen.
N</pre>]]></programlisting>
<para>Beachten Sie, dass <literal>&lt;</literal> und
<literal>&amp;</literal> nach wie vor als Sonderzeichen
erkannt werden. Daher wird in diesem Beispiel auch
<literal>&amp;lt;</literal> an Stelle von
<literal>&lt;</literal> verwendet. Aus dem gleichen
Grund wurde auch <literal>&amp;gt;</literal> an Stelle
von <literal>&gt;</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>&lt;big&gt;&lt;big&gt;Das ist
wesentlich
größer.&lt;/big&gt;&lt;/big&gt;</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>&lt;a href="..."&gt;</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>&lt;a name="..."&gt;</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 &amp; 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,&hellip;) 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 &ndash;
über die Elemente <sgmltag>sect3</sgmltag>,
<sgmltag>sect4</sgmltag> und <sgmltag>sect5</sgmltag> &ndash;
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&nbsp;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>&lt;book>
&lt;bookinfo>
&lt;title><replaceable>Titel</replaceable>&lt;/title>
&lt;author>
&lt;firstname><replaceable>Vorname</replaceable>&lt;/firstname>
&lt;surname><replaceable>Nachname</replaceable>&lt;/surname>
&lt;affiliation>
&lt;address>&lt;email><replaceable>E-Mail-Adresse</replaceable>&lt;/email>&lt;/address>
&lt;/affiliation>
&lt;/author>
&lt;copyright>
&lt;year><replaceable>1998</replaceable>&lt;/year>
&lt;holder role="mailto:<replaceable>E-Mail-Adresse</replaceable>"><replaceable>Vollständiger Name</replaceable>&lt;/holder>
&lt;/copyright>
&lt;releaseinfo>&#36;FreeBSD&#36;&lt;/releaseinfo>
&lt;abstract>
&lt;para><replaceable>Kurze Zusammenfassung des Buchinhaltes.</replaceable>&lt;/para>
&lt;/abstract>
&lt;/bookinfo>
&hellip;
&lt;/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>&lt;article>
&lt;articleinfo>
&lt;title><replaceable>Titel</replaceable>&lt;/title>
&lt;author>
&lt;firstname><replaceable>Vorname</replaceable>&lt;/firstname>
&lt;surname><replaceable>Nachname</replaceable>&lt;/surname>
&lt;affiliation>
&lt;address>&lt;email><replaceable>E-Mail-Adresse</replaceable>&lt;/email>&lt;/address>
&lt;/affiliation>
&lt;/author>
&lt;copyright>
&lt;year><replaceable>1998</replaceable>&lt;/year>
&lt;holder role="mailto:<replaceable>E-Mail-Adresse</replaceable>"><replaceable>Vollständiger Name</replaceable>&lt;/holder>
&lt;/copyright>
&lt;releaseinfo>&#36;FreeBSD&#36;&lt;/releaseinfo>
&lt;abstract>
&lt;para><replaceable>Kurze Zusammenfassung des Artikelinhalts.</replaceable>&lt;/para>
&lt;/abstract>
&lt;/articleinfo>
&hellip;
&lt;/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>
&hellip;
</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>
&hellip;
</sect1>
<sect1>
<title>Zweiter Abschnitt (1.2)</title>
<sect2>
<title>Erster Unterabschnitt (1.2.1)</title>
<sect3>
<title>Erster Unterunterabschnitt (1.2.1.1)</title>
&hellip;
</sect3>
</sect2>
<sect2>
<title>Zweiter Unterabschnitt (1.2.2)</title>
&hellip;
</sect2>
</sect1>
</chapter>]]></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>
&hellip;
</chapter>
<chapter>
<title>Was ist FreeBSD?</title>
&hellip;
</chapter>
<chapter>
<title>Die Geschichte von FreeBSD</title>
&hellip;
</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&amp;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&hellip;</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&hellip;</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 &amp;lt;stdio.h&amp;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 &lt;stdio.h&gt;
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>, &hellip;) 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 &amp;lt;stdio.h&amp;gt; <co id="co-ex-include"/>
int <co id="co-ex-return"/>
main(void)
{
printf("Hallo Welt\n"); <co id="co-ex-printf"/>
}</programlisting>
<calloutlist>
<callout arearefs="co-ex-include">
<para>Bindet die Headerdatei <filename>stdio.h</filename> ein.</para>
</callout>
<callout arearefs="co-ex-return">
<para>Bestimmt den Typ des Rückgabewertes von <function>main()</function>.</para>
</callout>
<callout arearefs="co-ex-printf">
<para>Ruft die Funktion <function>printf()</function> auf, die
<literal>Hallo Welt!</literal> auf der Standardausgabe ausgibt</para>
</callout>
</calloutlist>]]></programlisting>
<para>Darstellung:</para>
<para>Am Ende sollte Ihr Programm wie folgt aussehen:</para>
<programlisting>#include &amp;lt;stdio.h&amp;gt; <co id="co-ex-include"/>
int <co id="co-ex-return"/>
main(void)
{
printf("Hallo Welt\n"); <co id="co-ex-printf"/>
}</programlisting>
<calloutlist>
<callout arearefs="co-ex-include">
<para>Bindet die Headerdatei <filename>stdio.h</filename> ein.</para>
</callout>
<callout arearefs="co-ex-return">
<para>Bestimmt den Typ des Rückgabewertes von <function>main()</function>.</para>
</callout>
<callout arearefs="co-ex-printf">
<para>Ruft die Funktion <function>printf()</function> auf, die
<literal>Hallo Welt!</literal> auf der Standardausgabe ausgibt</para>
</callout>
</calloutlist>
</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>&lt;informaltable frame="none"&gt;</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>&amp;prompt.root;</literal> und
<literal>&amp;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>&amp;prompt.root;</literal> oder
<literal>&amp;prompt.user;</literal> eingesetzt
werden. Beide Entitäten können auch
außerhalb von <sgmltag>screen</sgmltag>
verwendet werden.</para>
<note>
<para><literal>&amp;prompt.root;</literal> und
<literal>&amp;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>&amp;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>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
%man; &hellip; ]&gt;</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>&amp;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>, &amp;man.mailq.1;, und &amp;man.newaliases.1;.</para>
<para>Mittels der Option <option>-bp</option> kann
<citerefentry><refentrytitle>sendmail</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry> den Status der Mailwarteschlange ausgeben.
Der Status der Mailwarteschlange kann durch den Befehl
<command>sendmail -bp</command> überprüft werden.</para>]]></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>&amp;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>&lt;mediaobject>
&lt;imageobject>
&lt;imagedata fileref="bild1"> <co id="co-image-ext"/>
&lt;/imageobject>
&lt;textobject>
&lt;literallayout class="monospaced">+ - - - - - - - - - - - - - - -+ <co id="co-image-literal"/>
| A |
+- - - - - - - - - - - - - - -+&lt;/literallayout>
&lt;/textobject>
&lt;textobject>
&lt;phrase>Ein Bild&lt;/phrase> <co id="co-image-phrase"/>
&lt;/textobject>
&lt;/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>&hellip;
IMAGES= bild1.eps bild2.png bild3.png
&hellip;</programlisting>
<para>Eine andere Möglichkeit wäre:</para>
<programlisting>&hellip;
IMAGES= bild1.eps
IMAGES+= bild2.png
IMAGES+= bild3.png
&hellip;</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>&lt;mediaobject>
&lt;imageobject>
&lt;imagedata fileref="kapitel1/bild1"> <co id="co-image-dir"/>
&lt;/imageobject>
&hellip;
&lt;/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>&hellip;
IMAGES= kapitel1/bild1.png
&hellip;</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 &ndash; 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 &ndash; 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>
Reference in a new issue View git blame Copy permalink