diff options
Diffstat (limited to 'de_DE.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml')
| -rw-r--r-- | de_DE.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml | 2992 |
1 files changed, 2992 insertions, 0 deletions
diff --git a/de_DE.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml b/de_DE.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml new file mode 100644 index 0000000000..bb89cc89b4 --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml @@ -0,0 +1,2992 @@ +<?xml version="1.0" encoding="iso-8859-1" standalone="no"?> +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ + $FreeBSDde$ + basiert auf: r38851 +--> + +<chapter id="sgml-markup"> + <title>SGML-Dokumente erstellen</title> + + <para>In diesem Kapitel werden die beiden vom FDP eingesetzen + Auszeichnungssprachen HTML und DocBook behandelt. Hierbei + beschränkt sich dieses Kapitel auf die Elemente, die bei der + täglichen Arbeit am ehesten zum Einsatz kommen werden.</para> + + <para>Beide Sprachen besitzen eine große Anzahl von Elementen. + Das erschwert es, das richtige Element in der richtigen Situation + auszuwählen. Aus diesem Grund werden zu jedem Element auch + immer Beispiele angeboten, die den richtigen Einsatz des Elements + verdeutlichen sollen.</para> + + <para>Es ist nicht das Ziel dieses Kapitels möglichst viele + Elemente beider Sprachen zu behandeln – dies wäre nur + eine Wiederholung der eigentlichen Sprachreferenz. Sofern es + Unklarheiten zur Verwendung einzelner Elemente und Auszeichnung + von bestimmten Sachverhalten gibt, können diese an &a.doc; + geschickt werden.</para> + + <note> + <title>Fluß- kontra Blockelemente</title> + + <!--@todo + Fussnote bzgl. der UEbersetzung von "inline" einfuegen. + Oliver Fischer + --> + + <para>Wenn im folgenden von + <emphasis>Flußelementen</emphasis> die Rede ist, sind + damit Elemente gemeint, die in einem Blockelement auftreten + können und keinen Zeilenumbruch hervorrufen. + <emphasis>Blockelemente</emphasis> hingegen erzeugen unter + anderem einen Zeilenumbruch<footnote><para>Die englische + Bezeichnung <foreignphrase>inline element</foreignphrase> + wurde in Anlehnung an das Wort <quote>Fließtext</quote> + mit <quote>Flußelement</quote> + übersetzt.</para></footnote>.</para> + </note> + + <sect1 id="sgml-markup-html"> + <title>HTML</title> + + <para>HTML, die <foreignphrase>HyperText Markup + Language</foreignphrase>, ist die Auszeichnungssprache des + Internets. Weitere Informationen zu HTML finden sich unter + <ulink url="http://www.w3.org/"></ulink>.</para> + + <para>Sie kommt bei der Erstellung der Webseiten des + FreeBSD-Projektes zum Einsatz. Für technische Dokumentationen + sollte HTML jedoch nicht eingesetzt werden, da DocBook eine + größere und bessere Auswahl an Elementen bietet. Folglich + sollte HTML nur für die FreeBSD-Webseiten verwendet werden.</para> + + <para>Die HTML-Spezifikation liegt bis jetzt in mehreren Versionen + vor: 1, 2, 3.0, 3.2 und (die aktuelle) 4.0. Von letzterer + existieren zwei Varianten: <quote>streng</quote> (HTML 4.0 + Strict) und <quote>locker</quote> (HTML 4.0 + Transitional).</para> + + <para>Die HTML-DTDs sind über den Port <filename + role="package">textproc/html</filename> verfügbar und werden + automatisch als Teil des Metaports <filename + role="package">textproc/docproj</filename> + mitinstalliert.</para> + + <sect2> + <title>Formale Öffentliche Bezeichner</title> + + <!--@todo Optimierungskandidat. Oliver Fischer --> + <para>Da es mehrere Version von HTML gibt, existieren auch + mehrere FÖPs, zu denen ein HTML-Dokument konform + erklärt werden kann. Die Mehrzahl der sich auf der + FreeBSD-Webseite befindenen HTML-Seiten sind zu der lockeren + Version von HTML 4.0 konform.</para> + + <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> + </sect2> + + <sect2> + <title>Die Elemente <sgmltag>head</sgmltag> und + <sgmltag>body</sgmltag></title> + + <para>Ein HTML-Dokument unterteilt sich normalerweise in zwei + Bereiche: <quote>head</quote> und <quote>body</quote>. Der + Kopf (<foreignphrase>head</foreignphrase>) enthält Metadaten + wie den Dokumententitel und Angaben zum Autor. Der Rumpf + (<foreignphrase>body</foreignphrase>) umfaßt den eigentlichen + Dokumenteninhalt, der für den Leser bestimmt ist. In einem + HTML-Dokument werden diese Bereiche über die Elemente + <sgmltag>head</sgmltag> und <sgmltag>body</sgmltag> + voneinander abgegrenzt. Beide sind Kinder des Wurzelelementes + <sgmltag>html</sgmltag>.</para> + + <example> + <title>Die Struktur eines HTML-Dokumentes</title> + + <programlisting><html> + <head> + <title><replaceable>Der Dokumententitel</replaceable></title> + </head> + + <body> + + … + + </body> +</html></programlisting> + </example> + </sect2> + + <sect2> + <title>Blockelemente</title> + + <sect3> + <title>Überschriften</title> + + <para>HTML kennt sechs verschiedene Elemente, mit denen + Überschriften ausgezeichnet werden können. Das bekannteste + Element ist <sgmltag>h1</sgmltag>, das sich am Anfang der + Überschriftenhierarchie befindet. <sgmltag>h1</sgmltag> + folgen die Überschriftenelemente <sgmltag>h2</sgmltag> bis + <sgmltag>h6</sgmltag>. Der Inhalt von + <sgmltag>h<replaceable>N</replaceable></sgmltag> stellt den + Text der Überschrift dar.</para> + + <example> + <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>…</title> + + <para>Fügen Sie in eine der existierenden Übungsdateien folgendes ein:</para> + + <programlisting><![CDATA[<h1>Erstes Kapitel</h1> + +<!-- Hier steht die Einführung --> + +<h2>Das ist die Überschrift des ersten Kapitels</h2> + +<!-- Hier steht der Inhalt des ersten Kapitels --> + +<h3>Das ist die Überschrift des ersten Unterkapitels</h3> + +<!-- Hier steht der Inhalt des ersten Unterkapitels --> + +<h2>Das ist die Überschrift des zweiten Kapitels</h2> + +<!-- Hier steht der Inhalt des zweiten Kapitels -->]]></programlisting> + </example> + + <para>Eine HTML-Seite sollte immer nur eine Überschrift + <sgmltag>h1</sgmltag> haben. Dieser Überschrift können + beliebig viele Kapitel mit einer Überschrift + <sgmltag>h2</sgmltag> folgen, die selbst wiederum eine + beliebige Anzahl von Kapiteln mit einer Überschrift + <sgmltag>h3</sgmltag> enthalten können. Diese + Verschachtelung setzt sich bis zu Kapiteln mit einer + <sgmltag>h6</sgmltag>-Überschrift fort. Es sollte vermieden + werden, Elemente in der Überschriftenhierarchie + auszulassen.</para> + + <example> + <title>Falsche Verschachtelung von Überschriften</title> + + <para>Fügen Sie in eine der existierenden Übungsdateien folgendes ein:</para> + + <programlisting><![CDATA[<h1>Erstes Kapitel</h1> + +<!-- Allgemeines zum Dokument --> + +<h3>Unterkapitel</h3> + +<!-- h3 folgt direkt auf h1. h2 wurde ausgelassen -->]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Absätze</title> + + <para>Absätze können in HTML mit Hilfe des Elementes + <sgmltag>p</sgmltag> ausgezeichnet werden.</para> + + <example> + <title>Absätze mit dem Element <sgmltag>p</sgmltag></title> + + <para>Fügen Sie in eine der existierenden Übungsdateien folgendes ein:</para> + + <programlisting><![CDATA[<p>Das hier, das ist ein Absatz. Absätze können + andere Elemente enhalten.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Blockzitate</title> + + <para>Ein Blockzitat ist ein etwas umfangreicheres Zitat aus + einem anderen Text, das nicht zum aktuellen Absatz + gehört.</para> + + <example> + <title>Blockzitat</title> + + <para>Fügen Sie in eine der existierenden Übungsdateien + folgendes ein:</para> + + <programlisting><![CDATA[<blockquote> + <p>Artikel 1: Menschenwürde; Grundrechtsbindung der + staatlichen Gewalt</p> + + <ol> + <li> + <p>Die Würde des Menschen ist unantastbar. Sie zu achten + und zu schützen ist Verpflichtung aller staatlichen + Gewalten.</p> + </li> + <li> + <p>Das Deutsche Volk bekennt sich darum zu unverletzlichen + und unveräußerlichen Menschenrechten als Grundlage jeder + menschlichen Gemeinschaft, des Friedens und der + Gerechtigkeit in der Welt.</p> + </li> + <li> + <p>Die nachfolgenden Grundrechte binden Gesetzgebung, + vollziehende Gewalt und Rechtsprechung als + unmittelbar geltendes Recht.</p> + </li> + </ol> +</blockquote>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Listen</title> + + <para>HTML kennt drei Arten von Listen: sortierte, unsortierte + und Definitionslisten. Ein Eintrag in einer sortierten Liste + wird üblicherweise mit einer Nummer versehen, Einträge in + unsortierten Listen hingegen mit einem Aufzählungspunkt. + Definitionslisten wiederum bestehen aus zwei Teilen: Der + erste enthält den Begriff der definiert werden soll und der + zweite dessen Erläuterung.</para> + + <para>Sortierte Listen werden mit dem Element + <sgmltag>ol</sgmltag> (für + <foreignphrase><emphasis>o</emphasis>rdered + <emphasis>l</emphasis>ist</foreignphrase>) ausgezeichnet, + unsortierte Listen mit <sgmltag>ul</sgmltag> (für + <foreignphrase><emphasis>u</emphasis>nordered + <emphasis>l</emphasis>ist</foreignphrase>) und + Definitionslisten mit <sgmltag>dl</sgmltag>.</para> + + + <para>Listenpunkte sortierter und unsortierter Listen werden + mit dem Element <sgmltag>li</sgmltag> ausgezeichnet, + welches Text oder andere Blockelemente enthalten kann. + Begriffe, die in einer Definitionslisten enthalten sind, + werden mit dem Element <sgmltag>dt</sgmltag> (für + <foreignphrase><emphasis>d</emphasis>efinition + <emphasis>t</emphasis>erm</foreignphrase>) ausgezeichnet. + Die Erklärung zu diesem Begriff wird mit Hilfe des Elementes + <sgmltag>dd</sgmltag> (für <foreignphrase>definition + description</foreignphrase>) markiert. So wie + <sgmltag>li</sgmltag>, kann das Element + <sgmltag>dd</sgmltag> ebenfalls andere Blockelemente + aufnehmen.</para> + + <example> + <title>Listen mit <sgmltag>ul</sgmltag> und + <sgmltag>ol</sgmltag> erstellen</title> + + <para>Fügen Sie in eine der existierenden Übungsdateien + folgendes ein:</para> + + <programlisting><![CDATA[<p>Jetzt folgt eine unsortierte Liste. Wahrscheinlich werden + die einzelnen Einträge mit einem vorangehenden Punkt dargestellt.</p> + +<ul> + <li>Erster Eintrag</li> + + <li>Zweiter Eintrag</li> + + <li>Dritter Eintrag</li> +</ul> + +<p>Die zweite Liste ist sortiert und ihre Einträge bestehen aus mehreren Absätzen. + Jeder Listeneintrag ist nummeriert.</p> + +<ol> + <li><p>Das ist der erste Eintrag mit nur einem Absatz.</p></li> + + <li><p>Das ist der erste Absatz des zweiten Eintrags.</p> + + <p>Und das ist der zweite Absatz des zweiten Eintrags.</p></li> + + <li><p>Der dritte Eintrag besteht ebenfalls nur aus einem Eintrag.</p></li> +</ol>]]></programlisting> + </example> + + <example> + <title>Definitionslisten mit <sgmltag>dl</sgmltag> erstellen</title> + + <para>Fügen Sie in eine der existierenden Übungsdateien folgendes ein:</para> + + <programlisting><![CDATA[<dl> + <dt>Erster Begriff</dt> + + <dd><p>Erster Absatz der Erklärung</p> + + <p>Zweiter Absatz der Erklärung.</p></dd> + + <dt>Zweiter Begriff</dt> + + <dd><p>Erster Absatz der Erklärung.</p></dd> + + <dt>Dritter Begriff</dt> + + <dd>Erster Absatz der Erklärung zum dritten Begriff.</dd> +</dl>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Vorformatierter Text</title> + + <!--@todo Bezeichnung ,,Schrift mit fester Laufweite'' Richtig? + Oliver Fischer, 21.03.04 --> + <para>In einigen Fällen ist es gewollt, dass die Formatierung + eines Textes im Quelldokument erhalten bleibt, damit der + Leser diesen genau so sieht, wie ihn der Autor erstellt hat. + In der HTML-Spezifikation ist dafür das Element + <sgmltag>pre</sgmltag> vorgesehen, welches dafür sorgt, dass + Zeilenumbrüche erhalten bleiben und Leerzeichen nicht + zusammengefaßt werden. Browser verwenden für den + Inhalt des Elementes <sgmltag>pre</sgmltag> + üblicherweise eine Fixschrift.</para> + + <example> + <title>Vorformatierten Text mit <sgmltag>pre</sgmltag> erstellen</title> + + <para>Der Originaltext einer E-Mail läßt sich beispielsweise + wie folgt einbinden:</para> + + <!--<para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail + message;</para>--> + + <programlisting><![CDATA[<pre> From: nik@FreeBSD.org + To: freebsd-doc@FreeBSD.org + Subject: Neue Version verfügbar + + Es ist eine neue Version der Fibel für neue Mitarbeiter am + FreeBSD-Dokumentationsprojekt verfügbar: + + <URL:http://people.FreeBSD.org/~nik/primer/index.html> + + Kommentare und Anmerkungen sind willkommen. + + N</pre>]]></programlisting> + + <para>Beachten Sie, dass <literal><</literal> und + <literal>&</literal> nach wie vor als Sonderzeichen + erkannt werden. Daher wird in diesem Beispiel auch + <literal>&lt;</literal> an Stelle von + <literal><</literal> verwendet. Aus dem gleichen + Grund wurde auch <literal>&gt;</literal> an Stelle + von <literal>></literal> verwendet. Achten Sie also + stets auf Sonderzeichen, wenn Sie normalen Text + aus E-Mails, Programmcode oder einer anderen Quelle + kopieren.</para> + + </example> + </sect3> + + <sect3> + <title>Tabellen</title> + + <note> + <para>Die meisten Textbrowser, beispielsweise Lynx, können + Tabellen nicht besonders gut darstellen. Deshalb sollten + Auszeichnungsalternativen in Betracht gezogen werden, um + eine angemessene Darstellung sicherzustellen.</para> + </note> + + <para>Tabellen lassen sich in HTML mit Hilfe des Elements + <sgmltag>table</sgmltag> auszeichnen. Eine Tabelle setzt + sich aus einer oder mehreren Zeilen (<sgmltag>tr</sgmltag>) + zusammen, von denen jede mindestens eine Zelle + (<sgmltag>td</sgmltag>) enthält. Zellen können wiederum + andere Blockelemente, wie Absätze oder Listen, enthalten. + Auch können sie auch andere Tabellen aufnehmen, wobei die + Verschachtelungstiefe unbegrenzt ist. Soll die Tabellenzelle + nur einen Textabsatz enthalten, ist es nicht notwendig den + Text mit einem <sgmltag>p</sgmltag> zu umschließen.</para> + + <example> + <title>Einfache Tabelle mit <sgmltag>table</sgmltag></title> + + <para>Fügen Sie in eine der existierenden Übungsdateien folgendes ein:</para> + + <programlisting><![CDATA[<p>Eine einfache 2x2 Tabelle.</p> + +<table> + <tr> + <td>Obere linke Zelle</td> + + <td>Obere rechte Zelle</td> + </tr> + + <tr> + <td>Untere linke Zelle</td> + + <td>Untere rechte Zelle</td> + </tr> +</table>]]></programlisting></example> + + <para>HTML kennt die Möglichkeit, dass sich eine + Zelle mehrere Zeilen und/oder Spalten erstrecken kann. + Sollen beispielsweise mehrere Spalten zusammenfassen werden, + kann dies mit mit Hilfe des Attributes + <literal>colspan</literal> erreicht werden, indem man ihm + die Anzahl der zusammenzufassenden Spalten zuweist. + Ähnliches gilt für die Zusammenfassung von Zeilen: + Hierfür wird dem Attribut <literal>rowspan</literal> + die Anzahl der zusammenzufassenden Zeilen zugewiesen.</para> + + <example> + <title>Anwendung des Attributes <literal>rowspan</literal></title> + + <programlisting><![CDATA[<p>Diese Tabelle besteht aus einer langen Zelle auf der + linken Seite und zwei kleineren Zellen auf der rechten.</p> + +<table> + <tr> + <td rowspan="2">Lang und dünn</td> + </tr> + + <tr> + <td>Obere Zelle</td> + + <td>Untere Zelle</td> + </tr> +</table>]]></programlisting> + </example> + + <example> + <title>Anwendung des Attributes <literal>colspan</literal></title> + + <programlisting><![CDATA[<p>Eine breite Zeile oben und zwei schmalere Zeilen + darunter.</p> + +<table> + <tr> + <td colspan="2">Obere Zelle</td> + </tr> + <tr> + <td>Linke untere Zelle</td> + + <td>Rechte untere Zelle</td> + </tr> +</table>]]></programlisting> + </example> + + <example> + <title>Gemeinsame Anwendung der Attrbute <literal>rowspan</literal> und + <literal>colspan</literal></title> + + <programlisting><![CDATA[<p>Eine Tablle mit 3-mal-3 Zellen. Oben links + werden 2 mal 2 Zelle zusammengezogen.</p> + +<table> + <tr> + <td colspan="2" rowspan="2">Große obere linke Zelle</td> + + <td>Obere rechte Zelle</td> + </tr> + + <tr> + <!-- Da sich die zusammengefaßte Zelle über zwei Zeilen + erstreckt, befindet sich das die durch dieses <td> + definierte Zelle ganz rechts. --> + + <td>Mittlere rechte Zelle</td> + </tr> + + <tr> + <td>Untere linke Zelle</td> + + <td>Untere mittlere Zelle</td> + + <td>Untere rechte Zelle</td> + </tr> +</table>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>Flußelemente</title> + + <sect3> + <title>Hervorheben von Information</title> + + <para>Sollen sich bestimmte Informationen von anderen optisch + abheben, kann dies mit den HTML-Tags + <sgmltag>strong</sgmltag> und <sgmltag>em</sgmltag> erreicht + werden. <sgmltag>strong</sgmltag> stellt dabei eine + stärkere Hervorhebung als <sgmltag>em</sgmltag> dar, + wobei mit <sgmltag>strong</sgmltag> ausgezeichnete Elemente + fett und mit <sgmltag>em</sgmltag> ausgezeichnete Elemente + kursiv dargestellt werden. Allerdings ist diese Aussage + nicht verläßlich, da die Darstellung vom Browser + abhängig ist.</para> + + <example> + <title>Text mit <sgmltag>em</sgmltag> und <sgmltag>strong</sgmltag> + hervorheben</title> + + <programlisting><![CDATA[<p><em>Dieses</em> Wort ist hervorgehoben, + während <strong>dieses noch stärker hervorgehoben ist.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <!--? Was ist typografisch richtig: schräg oder kursiv? + Oliver Fischer --> + <title>Fett- und Schrägschrift</title> + + <para>Da mittels HTML auch Festlegungen über die + Darstellung getroffen werden können, gibt es die + Möglichkeit direkt zu bestimmen, dass bestimmte + Inhalte fett oder kursiv dargestellt werden sollen. Mit + <sgmltag>b</sgmltag> eingefaßte Inhalte werden fett + und mit <sgmltag>i</sgmltag> eingefaßte kursiv + dargestellt.</para> + + <example> + <title>Text mit <sgmltag>b</sgmltag> und <sgmltag>i</sgmltag> + formatieren</title> + + <programlisting><![CDATA[<p><b>Dieses</b> Wort wird fett dargestellt, +während <i>dieses</i> kursiv dargestellt wird.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Nicht-proportionale Schrift für Texte</title> + + <para>Der Tag <sgmltag>tt</sgmltag> erlaubt es, + Text in einer schreibmaschinenähnlichen + Schrift darzustellen.</para> + + <example> + <title>Nicht-proportionale Schrift mit + <sgmltag>tt</sgmltag></title> + + <programlisting><![CDATA[<p>Dieses Dokument wurde ursprünglich von + Nik Clayton geschrieben. Nick Clayton kann unter der E-Mail-Adresse + <tt>nik@FreeBSD.org</tt> erreicht werden.</p>]]></programlisting> + + </example> + </sect3> + + <sect3> + <title>Änderung der Schriftgröße</title> + + <para>HTML bietet auch Möglichkeiten, um Einfluß + auf die Schriftgröße zu nehmen, das heißt, + zu bestimmen, ob die Schrift größer oder kleiner + als die Standardschrift dargestellt werden soll. Es gibt + drei verschiedene Wege, dies zu erreichen:</para> + + <orderedlist> + <listitem> + <para>Mittels der Tags <sgmltag>big</sgmltag> und + <sgmltag>small</sgmltag> kann die + Darstellungsgröße des eingeschlossenen Textes + vergrößert respektive verkleinert werden. + HTML erlaubt es zudem, diese Tags zu verschachteln, so + dass auch <literal><big><big>Das ist + wesentlich + größer.</big></big></literal> + geschrieben werden kann.</para> + </listitem> + + <listitem> + <para>Das gleiche Ergebnis kann über die Zuweisung der + Werte <literal>1</literal> und <literal>-1</literal> an + das Attribut <sgmltag role="attribute">size</sgmltag> + des Tags <sgmltag>font</sgmltag> erreicht werden. Diese + Vorgehensweise sollte allerdings als veraltet betrachtet + werden, da der Einsatz eines CSS hierfür die bessere + Lösung darstellt.</para> + </listitem> + + <listitem> + <para>Über die Zuweisung von absoluten Werten im Bereich + von <literal>1</literal> bis <literal>7</literal> an das + Attribut <literal>size</literal> des Tags + <sgmltag>font</sgmltag> <footnote> + <para>Der Standardwert für <literal>size</literal> ist + <literal>3</literal>.</para></footnote>. Diese + Herangehensweise ist ebenfalls veraltet und sollte nicht + mehr angewandt werden.</para> + </listitem> + </orderedlist> + + <example> + <title>Schriftgröße ändern mit + <sgmltag>big</sgmltag>, <sgmltag>small</sgmltag> und + <sgmltag>font</sgmltag></title> + + <para>Die folgenden HTML-Schnipsel bewirken alle das gleiche:</para> + + <programlisting><![CDATA[<p>Dieser Text ist <small>etwas kleiner</small>. Dieser + jedoch <big>ein wenig größer</big>.</p> + +<p>Dieser Text ist <font size="-1">etwas kleiner</font>. Dieser + jedoch <font size="+1">ein wenig größer</font>.</p> + +<p>Dieser Text ist <font size="2">etwas kleiner</font>. Dieser + jedoch <font size="4">ein wenig größer</font>.</p>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2 id="links"> + <title>Links</title> + + <note> + <para>Bei Links handelt es sich ebenfalls Flußelemente.</para> + </note> + + <sect3> + <title>Auf andere Dokumente im WWW verweisen</title> + + <para>Um auf ein anderes Dokument im WWW zu verweisen, + müssen Sie die URL dieses Dokuments kennen.</para> + + <para>Links auf andere Dokumente im WWW werden in HTML durch + den Tag <sgmltag>a</sgmltag> und dessen Attribute <sgmltag + role="attribute">href</sgmltag>, das die Zieladresse + enthält, angelegt. Der Inhalt des Elementes wird selbst + zum Link und seine Darstellung erfolgt verschieden vom + übrigen Text. Meist geschieht das durch eine andere + Schriftfarbe oder dadurch, dass der Linktext + unterstrichen wird.</para> + + <example> + <title><literal><a href="..."></literal> benutzen</title> + + <programlisting><![CDATA[<p>Weitere Informationen stehen auf der + <a href="http://www.FreeBSD.org/">FreeBSD-Webseite</a> zur Verfügung.</p>]]></programlisting> + </example> + + <para>Beim Aufruf dieses Links wird das referenzierte Dokument vom + Browser geladen und mit dessen Seitenanfang dargestellt.</para> + </sect3> + + <sect3> + <title>Auf bestimmte Dokumentenabschnitte verweisen</title> + + <para>HTML unterstützt neben einfachen Links auch solche, die + auf einen bestimmten Abschnitt innerhalb eines Dokumentes + verweisen. Dazu müssen die Abschnitte, auf die verwiesen + werden soll, mit Hilfe von sogenannten <quote>Ankern</quote> + markiert werden. Diese Anker können ebenfalls mit Hilfe des + Tags <sgmltag>a</sgmltag> gesetzt werden, nur das anstelle + von <sgmltag role="attribute">href</sgmltag> das Attribut + <sgmltag role="attribute">name</sgmltag> gesetzt werden + muss.</para> + + <example> + <title>Anwendung von <literal><a name="..."></literal></title> + + <programlisting><![CDATA[<p><a name="absatz1">Auf</a> diesen Absatz kann mit + Hilfe seines Namens (<tt>absatz1</tt>) verwiesen werden.</p>]]></programlisting> + </example> + + <para>Um auf einen so gekennzeichneten Abschnitt zu verweisen, + muss die URL des Dokumentes um das Zeichen + <literal>#</literal> und den Namen des Zielankers erweitert + werden.</para> + + <example> + <title>Auf einen Abschnitt eines anderen Dokumentes + verweisen</title> + + <para>Für dieses Beispiel wird davon ausgegangen, dass der mit + <literal>absatz1</literal> gekennzeichnete Absatz sich in + der HTML-Datei <filename>foo.html</filename> + befindet.</para> + + <programlisting><![CDATA[<p>Weitere Informationen können im + <a href="foo.html#absatz1">ersten Absatz</a> der Datei + <tt>foo.html</tt> gefunden werden.</p>]]></programlisting> + </example> + + </sect3> + </sect2> + </sect1> + + <sect1 id="sgml-markup-docbook"> + <title>Die DocBook DTD</title> + + <para>DocBook wurde ursprüglich von HaL Computer Systems and + O'Reilly & Associates als DTD für das Erstellen von + technischen Dokumenten entwickelt + + <footnote><para>Einen kurzen historischen Abriss finden Sie unter + <ulink + url="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.</para> + </footnote>. + + Seit 1998 wird es vom <ulink + url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> + DocBook Technical Committee</ulink> gewartet. DocBook ist sehr + stark auf die Beschreibung von Inhalten, und nicht auf die + Darstellung des Inhalts ausgerichtet. Damit steht es im Gegensatz + zu LinuxDoc und HTML.</para> + + <note> + <title>Formelle und informelle Elemente</title> + + <para>Einige Elemente der DocBook DTD sind in zwei Varianten + vorhanden: <emphasis>formell</emphasis> und + <emphasis>informell</emphasis>. Üblicherweise besitzt die + formelle Variante einen Titel, dem der eigentliche + Elementeninhalt folgt. Die informelle Variante hingegen hat + keinen Titel.</para> + </note> + + <para>Die DocBook DTD ist in der Ports-Sammlung im Port <filename + role="package">textproc/docbook</filename> enthalten und wird + bei der Installation des Metaports <filename + role="package">textproc/docproj</filename> automatisch + mitinstalliert.</para> + + <sect2> + <title>Die FreeBSD-Erweiterungen</title> + + <para>Für das FDP wurde die DocBook DTD durch das + FreeBSD-Dokumentationsproject um zusätzliche Elemente + erweitert, um damit präzisiere + Auszeichnungsmöglichkeiten zur Verfügung zu haben. + Sofern im folgenden FreeBSD-spezifische Elemente genutzt + werden, wird explizit darauf hingewiesen werden.</para> + + <para>Wenn nachfolgend im Text der Begriff + <quote>DocBook</quote> verwendet wird, ist damit die durch das + FDP erweiterte Version der DocBook DTD gemeint.</para> + + <note> + <para>Die durch das FDP vorgenommenen Erweiterungen sind nicht + FreeBSD-spezifisch. Sie wurden lediglich vorgenommen, da sie + für die Arbeit des FDPs als nützlich erschienen. + Für den Fall, das in den anderen *nix-Lagern (NetBSD, + OpenBSD, Linux,…) Interesse daran besteht, gemeinsam + eine Standarderweiterung für die DocBook DTD zu + entwickeln, kann mit dem &a.doceng; Verbindung aufgenommen + werden.</para> + </note> + + <para>Zum jetzigen Zeitpunkt sind die FreeBSD-Erweiterungen + nicht Bestandteil der Ports-Sammlung. Sie werden im + &os;-Subversion-Repository (<ulink + url="http://svnweb.FreeBSD.org/doc/head/share/sgml/freebsd.dtd">head/share/sgml/freebsd.dtd</ulink>) + verwaltet.</para> + </sect2> + + <sect2> + <title>Formelle Öffentliche Bezeichner</title> + + <para>In Übereinstimmung mir der DocBook-Richtlinie zur + Erstellung von Bezeichnern für DocBook-Erweiterungen lautet + der Bezeichner der erweiterten FreeBSD-Variante:</para> + + <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting> + </sect2> + + <sect2 id="docbookstructure"> + <title>Die Struktur von DocBook-Dokumenten</title> + + <para>DocBook erlaubt es, Dokumente auf verschiedene Weise zu + strukturieren. Innerhalb des FDPs werden hauptsächlich zwei + Arten von DocBook-Dokumenten verwendet: Buch und Artikel. + Beide unterscheiden sich darin, dass ein Buch auf der obersten + Ebene durch <sgmltag>chapter</sgmltag>-Elemente strukturiert + wird. Sollte das noch nicht ausreichend sein, können die + einzelnen Kapitel eines Buches mit Hilfe des Elementes + <sgmltag>part</sgmltag> in Teile aufgespalten werden. Das + Handbuch ist beispielsweise auf diese Weise aufgebaut.</para> + + <para>Kapitel (<sgmltag>chapter</sgmltag>) können weiterhin in + Unterkapitel unterteilt werden. Diese werden durch die + Elemente <sgmltag>sect1</sgmltag> ausgezeichnet. Soll ein + Unterkapitel selbst weitere Unterkapitel enthalten, kann das + über das Element <sgmltag>sect2</sgmltag> geschehen. Diese + Unterteilung kann bis zur Tiefe von fünf Unterkapiteln – + über die Elemente <sgmltag>sect3</sgmltag>, + <sgmltag>sect4</sgmltag> und <sgmltag>sect5</sgmltag> – + fortgeführt werden. Der eigentliche Inhalt, um den es ja in + dem Artikel oder Buch geht, wird unterhalb der hier genannten + Elemente eingefügt.</para> + + <para>Vom Aufbau her ist ein Artikel ist einfacher strukturiert + als ein Buch. So kann ein Artikel beispielsweise keine Kapitel + (<sgmltag>chapter</sgmltag>) enthalten. Stattdessen kann der + Inhalt eines Artikels nur durch die schon bekannten + <sgmltag>sect<replaceable>N</replaceable></sgmltag>-Elemente + in einen oder mehrere Abschnitte gegliedert werden. + Überlegen Sie sich vor dem Schreiben eines Textes, + ob der zu schreibende Text am + besten als Buch oder als Artikel angelegt wird. Artikel eignen + sich besser für Texte, die nicht in mehrere Kapitel + aufgeteilt werden müssen und mit einem Umfang von + ungefähr 20 bis 25 Seiten vergleichsweise kurz sind. + Natürlich ist das nur eine Richtlinie. Bücher sind + dementsprechend am besten für lange Texte geeignet, die + sich sinnvoll in Kapitel unterteilen lassen und + möglichweiser noch Anhänge und ähnliches + enthalten können.</para> + + <para>Alle <ulink url="&url.base;/de/docs.html">Tutorien von + FreeBSD</ulink> sind als Artikel verfaßt, während + hingegen die <ulink + url="&url.books.faq;/index.html">FreeBSD-FAQ</ulink> und das <ulink + url="&url.books.handbook;/index.html">FreeBSD-Handbuch</ulink> als + Bücher verfaßt wurden.</para> + + <sect3> + <title>Bücher schreiben</title> + + <para>Der Inhalt eines Buches wird in einem + <sgmltag>book</sgmltag>-Element abgelegt. Neben dem + Textteil des Buches kann dieses Element weitergehende + Informationen über das Buch selbst, + wie Meta-Informationen zum Erstellen eines + Stichwortverzeichnisses oder zusätzliche + Inhalte zum Erstellen einer Titelei, enthalten. Diese + zusätzlichen Inhalte sollten in einem + <sgmltag>bookinfo</sgmltag>-Element abgelegt werden.</para> + + <example> + <title>Buchvorlage <sgmltag>book</sgmltag> mit + <sgmltag>bookinfo</sgmltag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + <programlisting><book> + <bookinfo> + <title><replaceable>Titel</replaceable></title> + <author> + <firstname><replaceable>Vorname</replaceable></firstname> + <surname><replaceable>Nachname</replaceable></surname> + <affiliation> + <address><email><replaceable>E-Mail-Adresse</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>E-Mail-Adresse</replaceable>"><replaceable>Vollständiger Name</replaceable></holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para><replaceable>Kurze Zusammenfassung des Buchinhaltes.</replaceable></para> + </abstract> + </bookinfo> + + … + +</book></programlisting> + </example> + </sect3> + + <sect3> + <title>Artikel schreiben</title> + + <para>Der Inhalt eines Artikels wird in einem + <sgmltag>article</sgmltag>-Element abgelegt. Neben + dem Textteil kann dieses Element weitere Teile, + wie Meta-Informationen zum Erstellen eines + Stichwortverzeichnisses oder zusätzliche + Inhalte zum Erstellen einer Titelei, enthalten. + Analog zu einem Buch, sollten diese Informationen in einem + <sgmltag>articleinfo</sgmltag>-Element abgelegt + werden.</para> + + <example> + <title>Artikelvorlage <sgmltag>article</sgmltag> mit + <sgmltag>articleinfo</sgmltag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + <programlisting><article> + <articleinfo> + <title><replaceable>Titel</replaceable></title> + + <author> + <firstname><replaceable>Vorname</replaceable></firstname> + <surname><replaceable>Nachname</replaceable></surname> + <affiliation> + <address><email><replaceable>E-Mail-Adresse</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>E-Mail-Adresse</replaceable>"><replaceable>Vollständiger Name</replaceable></holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para><replaceable>Kurze Zusammenfassung des Artikelinhalts.</replaceable></para> + </abstract> + </articleinfo> + + … + +</article></programlisting> + </example> + </sect3> + + <sect3> + <title>Kapitel</title> + + <para>Kapitel werden mit dem + <sgmltag>chapter</sgmltag>-Element angelegt und müssen ein + <sgmltag>title</sgmltag>-Element enthalten. Verwendet werden + können sie nur in Büchern.</para> + + <example> + <title>Ein einfaches Kapitel</title> + + <programlisting><![CDATA[<chapter> + <title>Kapitelüberschrift</title> + + … +</chapter>]]></programlisting> + </example> + + <para>Kapitel können nicht leer sein. Nebem einem + <sgmltag>title</sgmltag>-Element müssen sie weiteren Inhalt + beinhalten. Falls ein leeres Kapitel benötig wird, kann dies + durch das Einfügen eines leeren Absatzes + (<sgmltag>para</sgmltag>) erreicht werden.</para> + + <example> + <title>Ein leeres Kapitel</title> + + <programlisting><![CDATA[<chapter> + <title>Das ist ein leeres Kapitel</title> + + <para></para> +</chapter>]]></programlisting> + </example> + </sect3> + + <sect3 id="unterkapitel"> + <title>Unterkapitel</title> + + <!-- Bei der Uebersetzung dieser Stelle bin ich + bewusst vom Original abgewichen, da ich die + Begriffe Kapitel und Kapitel anstatt + Kapitel und Abschnitt benutze. Eine + originalgetreue Uebersetzung wuerde somit an dieser + Stelle nur zu Verwirrung fuehren. + Oliver Fischer, 14.04.2004 --> + + <para>Bücher werden auf der obersten Gliederungsebene + durch <sgmltag>chapter</sgmltag>-Elemente in Kapitel + unterteilt. Eine weitergehende Untergliederung kann durch + das Anlegen von Unterkapiteln erreicht werden. Im Gegensatz + zu Kapiteln, die durch <sgmltag>chapter</sgmltag>-Elemente + ausgezeichnet werden, erfolgt die Auszeichnung von + Unterkapitel mit dem Element + <sgmltag>sect<replaceable>n</replaceable></sgmltag>. Das + <replaceable>n</replaceable> in Elementnamen trifft eine + Aussage über die Gliederungstiefe, auf der sich das + Unterkapitel befindet. Ein <sgmltag>sect1</sgmltag>-Element + kann mehrere Elemente vom Typ <sgmltag>sect2</sgmltag> + enthalten, die die Unterkapitel der + nächsten Gliederungsebene darstellen. + <sgmltag>sect5</sgmltag> ist das letzte Element, das auf + diese Art zur Gliederung eingesetzt werden kann.</para> + + <example> + <title>Unterkapitel</title> + + <programlisting><![CDATA[<chapter> + <title>Ein Beispielkapitel</title> + + <para>Ein beliebiger Text.</para> + + <sect1> + <title>Erster Abschnitt (1.1)</title> + + … + </sect1> + + <sect1> + <title>Zweiter Abschnitt (1.2)</title> + + <sect2> + <title>Erster Unterabschnitt (1.2.1)</title> + + <sect3> + <title>Erster Unterunterabschnitt (1.2.1.1)</title> + + … + </sect3> + </sect2> + + <sect2> + <title>Zweiter Unterabschnitt (1.2.2)</title> + + … + </sect2> + </sect1> +</chapter>]]></programlisting> + </example> + + <note> + <para>Die Unterkapitel dieses Beispiels wurden zu + Demonstrationszwecken manuell durchnummeriert. In + <quote>normalen</quote> Dokumenten wird diese Aufgabe von + den Stylesheets übernommen.</para> + </note> + </sect3> + + <sect3> + <title>Bücher mittels <sgmltag>part</sgmltag> + unterteilen</title> + + <para>In den Fällen, in denen die Unteilung eines Buches in + Kapitel nicht ausreichend ist, können mehrere + Kapitel mit dem Element <sgmltag>part</sgmltag> zu + einem Teil zusammengefasst werden.</para> + + <programlisting><![CDATA[<part> + <title>Einführung</title> + + <chapter> + <title>Überblick</title> + + … + </chapter> + + <chapter> + <title>Was ist FreeBSD?</title> + + … + </chapter> + + <chapter> + <title>Die Geschichte von FreeBSD</title> + + … + </chapter> +</part>]]></programlisting> + </sect3> + </sect2> + + <sect2> + <title>Blockelemente</title> + + <sect3> + <title>Absätze</title> + + <para>DocBook kennt drei Arten von Absätzen: Absätze + mit Überschrift (<sgmltag>formalpara</sgmltag>), + normale Absätze (<sgmltag>para</sgmltag>) und einfache + Absätze (<sgmltag>simpara</sgmltag>).</para> + + <para>Normale Absätze und einfache Absätze + unterscheiden sich dadurch, dass innerhalb von + <sgmltag>para</sgmltag> Blockelemente erlaubt sind, + innerhalb von <sgmltag>simpara</sgmltag> hingegen nicht. Es + ist empfehlenswert, <sgmltag>para</sgmltag> den Vorzug + zu geben.</para> + + <example> + <title>Absatz mit <sgmltag>para</sgmltag></title> + + <programlisting><![CDATA[<para>Das ist ein Absatz. Absätze können fast jedes andere + Element aufnehmen.</para>]]></programlisting> + + <para>Darstellung:</para> + + <para>Das ist ein Absatz. Absätze können fast jedes andere + Element aufnehmen.</para> + </example> + </sect3> + + <sect3> + <title>Blockzitate</title> + + <para>Blockzitate sind textlich umfangreichere Zitate aus + einem anderen Text, die nicht innerhalb des aktuellen + Absatzes angezeigt werden sollen. Wahlweise können + Blockzitate eine Überschrift haben und die Zitatquelle + nennen.</para> + + <example> + <title><sgmltag>blockquote</sgmltag></title> + + <programlisting><![CDATA[<para>Ein Auszug aus dem Grundgesetz:</para> + +<blockquote> + <title>Menschenwürde; Grundrechtsbindung der staatlichen Gewalt</title> + + <attribution>Aus dem Grundgesetz</attribution> + + <orderedlist> + <listitem> + <para>Die Würde des Menschen ist unantastbar. Sie zu achten + und zu schützen ist Verpflichtung aller staatlichen + Gewalten.</para> + </listitem> + <listitem> + <para>Das Deutsche Volk bekennt sich darum zu unverletzlichen + und unveräußerlichen Menschenrechten als Grundlage jeder + menschlichen Gemeinschaft, des Friedens und der + Gerechtigkeit in der Welt.</para> + </listitem> + <listitem> + <para>Die nachfolgenden Grundrechte binden Gesetzgebung, + vollziehende Gewalt und Rechtsprechung als + unmittelbar geltendes Recht.</para> + </listitem> + </orderedlist> +</blockquote>]]></programlisting> + + <para>Darstellung:</para> + + <blockquote> + <title>Menschenwürde; Grundrechtsbindung der + staatlichen Gewalt</title> + + <attribution>Aus dem Grundgesetz</attribution> + + <orderedlist> + <listitem> + <para>Die Würde des Menschen ist unantastbar. Sie + zu achten und zu schützen ist Verpflichtung + aller staatlichen Gewalten.</para> + </listitem> + <listitem> + <para>Das Deutsche Volk bekennt sich darum zu + unverletzlichen und unveräußerlichen + Menschenrechten als Grundlage jeder menschlichen + Gemeinschaft, des Friedens und der Gerechtigkeit in + der Welt.</para> + </listitem> + <listitem> + <para>Die nachfolgenden Grundrechte binden + Gesetzgebung, vollziehende Gewalt und Rechtsprechung + als unmittelbar geltendes Recht.</para> + </listitem> + </orderedlist> + </blockquote> + </example> + </sect3> + + <sect3> + <title>Tipps, Anmerkungen, Warnungen, wichtige Informationen + und Randbemerkungen</title> + + <para>In bestimmten Fällen kann es nützlich sein, + dem Leser zusätzliche Informationen zu geben, die sich + vom Haupttext abheben, damit der Leser sie besser wahrnimmt. + Abhängig von der Art der Information, können + solche Stellen mit einem der Elemente <sgmltag>tip</sgmltag> + (für Tipps), <sgmltag>note</sgmltag> (für + Anmerkungen), <sgmltag>warning</sgmltag> (für + Warnungen), <sgmltag>caution</sgmltag> (für besonders + ernstzunehmende Warnungen) und <sgmltag>important</sgmltag> + (für wichtige Anmerkungen) ausgezeichnet werden. Trifft + keines dieser Element für die auszuzeichnende Stelle + zu, sollte diese mit dem Element <sgmltag>sidebar</sgmltag> + ausgezeichnet werden.</para> + + <para>Da die richtige Einordnung einer auszuzeichnenden + Textstelle nicht immer leicht zu treffen ist, werden in der + DocBook-Dokumentation folgende Empfehlungen gegeben:</para> + + <itemizedlist> + <listitem> + <para>Eine Anmerkung (<sgmltag>note</sgmltag>) ist eine + Information, die von jedem Leser beachtet werden + sollte.</para> + </listitem> + + <listitem> + <para>Eine wichtige Anmerkung + (<sgmltag>important</sgmltag>) eine Variation einer + Anmerkung.</para> + </listitem> + + <listitem> + <para>Eine Warnung (<sgmltag>warning</sgmltag>) + betrifft einen möglichen Hardwareschaden + oder weist auf eine Gefahr für Leib und Leben + hin.</para> + </listitem> + + <listitem> + <para>Eine besonders ernstzunehmende Warnung + (<sgmltag>caution</sgmltag>) betrifft einen möglichen + Datenverlust oder Softwareschaden.</para> + </listitem> + </itemizedlist> + + <example> + <title><sgmltag>warning</sgmltag></title> + + <programlisting><![CDATA[<warning> + <para>Wenn Sie FreeBSD auf Ihrer Festplatte installieren, + kann es sein, da&szlig; Sie Windows nie mehr benutzen wollen.</para> +</warning>]]></programlisting> + </example> + + <para>Eine Warnung wird wie folgt dargestellt:</para> + + <warning> + <para>Wenn Sie FreeBSD auf Ihrer Festplatte installieren, + kann es sein, dass Sie Windows nie mehr benutzen wollen.</para> + </warning> + </sect3> + + <sect3> + <title>Listen und Handlungsanweisungen</title> + + <para>Listen sind ein oft gebrauchtes Hilfsmittel, wenn es + darum geht, Informationen für den Benutzer + übersichtlich darzustellen oder eine Abfolge von + Arbeitsschritten zu beschreiben, die notwendig sind, um ein + bestimmtes Ziel zu erreichen. Zur Auszeichnung von Listen + stellt DocBook die Elemente <sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag> und + <sgmltag>procedure</sgmltag> zur Verfügung.<footnote> + <para>DocBook kennt noch andere Elemente für die + Auszeichnung von Listen, die an dieser Stelle jedoch + nicht behandelt werden.</para> + </footnote>.</para> + + <para><sgmltag>itemizedlist</sgmltag> und + <sgmltag>orderedlist</sgmltag> ähneln sehr stark ihren + HTML-Gegenstücken <sgmltag>ul</sgmltag> und + <sgmltag>ol</sgmltag>. Beide Listenarten müssen + mindestens ein Element <sgmltag>listitem</sgmltag> + enthalten. Das <sgmltag>listitem</sgmltag> Element + muss mindestens ein weiteres Blockelement + enthalten.</para> + + <para><sgmltag>procedure</sgmltag> unterscheidet sich ein + wenig von den vorhergehenden. Es enthält + <sgmltag>step</sgmltag>-Elemente, die wiederum + <sgmltag>step</sgmltag>- oder + <sgmltag>substel</sgmltag>-Elemente enthalten können. + Ein <sgmltag>step</sgmltag>-Element kann nur Blockelemente + aufnehmen.</para> + + <example> + <title><sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag> und + <sgmltag>procedure</sgmltag></title> + + <programlisting><![CDATA[<itemizedlist> + <listitem> + <para>Das ist das erste Listenelement.</para> + </listitem> + + <listitem> + <para>Das ist das zweite Listenelement.</para> + </listitem> +</itemizedlist> + +<orderedlist> + <listitem> + <para>Das ist das erste Aufzählungselement.</para> + </listitem> + + <listitem> + <para>Das ist das zweite Aufzählungselement.</para> + </listitem> +</orderedlist> + +<procedure> + <step> + <para>Machen Sie zuerst dies.</para> + </step> + + <step> + <para>Und dann machen Sie das..</para> + </step> + + <step> + <para>Und jetzt noch das…</para> + </step> +</procedure>]]></programlisting> + + <para>Darstellung:</para> + + <itemizedlist> + <listitem> + <para>Das ist das erste Listenelement.</para> + </listitem> + + <listitem> + <para>Das ist das zweite Listenelement.</para> + </listitem> + </itemizedlist> + + <orderedlist> + <listitem> + <para>Das ist das erste Aufzählungselement.</para> + </listitem> + + <listitem> + <para>Das ist das zweite Aufzählungselement.</para> + </listitem> + </orderedlist> + </example> + + <procedure> + <step> + <para>Machen Sie zuerst dies.</para> + </step> + + <step> + <para>Und dann machen Sie das..</para> + </step> + + <step> + <para>Und jetzt noch das…</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Dateiinhalte auszeichnen</title> + + <para>Technische Dokumente enthalten oft auch + Konfigurationsbeispiele oder Quellcodeschnipsel. Zur + Auszeichnung dieser Inhalte, stellt Docbook das Element + <sgmltag>programmlisting</sgmltag> zur Verfügung. Im + Gegensatz zu anderen DocBook-Elementen wird der + Elementinhalt von <sgmltag>programmlisting</sgmltag> + <emphasis>nicht</emphasis> normalisiert, das heißt, + dass alle Leerzeichen, Tabulatoren und + Zeilenumbrüche unverändert übernommen werden. + Aus diesem Grund ist es unter anderem wichtig, dass + sich der öffende Tag in der selben Zeile wie der Anfang + des darzustellenden Textes befindet. Gleiches gilt für + den schließenden Tag: Er muss sich am Ende der + letzten Zeile befinden. Wird das nicht beachtet, kann es + sein, dass unerwartete Leerzeichen und Leerzeilen in + der Ausgabe auftauchen.</para> + + <example> + <title><sgmltag>programlisting</sgmltag></title> + + <programlisting><![CDATA[<para>Am Ende sollte Ihr Programm wie folgt + aussehen:</para> + +<programlisting>#include &lt;stdio.h&gt; + +int +main(void) +{ + printf("Hallo Welt!\n"); +}</programlisting>]]></programlisting> + + <para>Die spitzen Klammern der + <literal>#include</literal>-Anweisung können nicht direkt + verwendet werden, sondern müssen über ihre Entitäten + eingebunden werden.</para> + + <para>Darstellung:</para> + + <para>Am Ende sollte Ihr Programm wie folgt aussehen:</para> + + <programlisting>#include <stdio.h> + +int +main(void) +{ + printf("Hallo Welt!\n"); +}</programlisting> + </example> + </sect3> + + <sect3> + <title>Textanmerkungen</title> + + <para>Textanmerkungen<footnote><para> + auf Englisch: + <foreignphrase>callout</foreignphrase></para></footnote> + sind ein Mechanismus, um auf bestimmte Stellen in einem + vorhergehenden Beispiel oder Text zu verweisen.</para> + + <para>Um solche Verweise anzulegen, müssen die betreffenden + Stellen in den Beispielen + (<sgmltag>programlisting</sgmltag>, + <sgmltag>literallayout</sgmltag>, …) mit + <sgmltag>co</sgmltag>-Elementen markiert werden, wobei jedes + Element ein eindeutiges <literal>id</literal>-Attribut + besitzen muss. Anschließend sollte ein + <sgmltag>calloutlist</sgmltag>-Element eingefügt werden, + dessen Elemente sich auf die <sgmltag>co</sgmltag>-Elemente + des Beispiels beziehen und die jeweiligen Anmerkungen + enthalten.</para> + + <example> + <title>Das <sgmltag>co</sgmltag>- und das + <sgmltag>calloutlist</sgmltag>-Element</title> + + <programlisting><![CDATA[<para>Am Ende sollte Ihr Programm wie folgt + aussehen:</para> + +<programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include"/> + +int <co id="co-ex-return"/> +main(void) +{ + printf("Hallo Welt\n"); <co id="co-ex-printf"/> +}</programlisting> + +<calloutlist> + <callout arearefs="co-ex-include"> + <para>Bindet die Headerdatei <filename>stdio.h</filename> ein.</para> + </callout> + + <callout arearefs="co-ex-return"> + <para>Bestimmt den Typ des Rückgabewertes von <function>main()</function>.</para> + </callout> + + <callout arearefs="co-ex-printf"> + <para>Ruft die Funktion <function>printf()</function> auf, die + <literal>Hallo Welt!</literal> auf der Standardausgabe ausgibt</para> + </callout> +</calloutlist>]]></programlisting> + + <para>Darstellung:</para> + + <para>Am Ende sollte Ihr Programm wie folgt aussehen:</para> + + <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include"/> + +int <co id="co-ex-return"/> +main(void) +{ + printf("Hallo Welt\n"); <co id="co-ex-printf"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-ex-include"> + <para>Bindet die Headerdatei <filename>stdio.h</filename> ein.</para> + </callout> + + <callout arearefs="co-ex-return"> + <para>Bestimmt den Typ des Rückgabewertes von <function>main()</function>.</para> + </callout> + + <callout arearefs="co-ex-printf"> + <para>Ruft die Funktion <function>printf()</function> auf, die + <literal>Hallo Welt!</literal> auf der Standardausgabe ausgibt</para> + </callout> + </calloutlist> + </example> + </sect3> + + <sect3> + <title>Tabellen</title> + + <para>Im Gegensatz zu HTML ist es nicht notwendig, Tabellen zu + Layoutzwecken einzusetzen, da die Layoutaufgabe von den + Stylesheets übernommen wird. Stattdessen sollten Tabellen + nur für die Auszeichnung von Daten in Tabellenform genutzt + werden.</para> + + <para>Vereinfacht betrachtet (für Details sollte die + DocBook-Dokumentation zu Rate gezogen werden) besteht eine + Tabelle, die entweder als formelle oder als informelle + Tabelle angelegt werden kann, aus einem + <sgmltag>table</sgmltag>-Element. Dieses Element selbst + beinhaltet mindestens ein Element <sgmltag>tgroup</sgmltag>, + das über ein Attribut die Spaltenanzahl der Tabelle + bestimmt. Innerhalb des Elementes <sgmltag>tgroup</sgmltag> + kann sich ein Element <sgmltag>thead</sgmltag> mit den + Spaltenüberschriften und ein Element + <sgmltag>tbody</sgmltag> mit dem eigentlichen Tabelleninhalt + befinden. Beide Elemente beinhalten + <sgmltag>row</sgmltag>-Elemente, die wiederum + <sgmltag>entry</sgmltag>-Elemente beinhalten. Jedes + <sgmltag>entry</sgmltag>-Element stellt eine einzelne + Tabellenzelle dar.</para> + + <example> + <title>Tabellen mittels <sgmltag>informaltable</sgmltag> + auszeichnen</title> + + <programlisting><![CDATA[<informaltable pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Spaltenüberschrift 1</entry> + <entry>Spaltenüberschrift 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Zeile 1, Spalte 1</entry> + <entry>Zeile 1, Spalte 2</entry> + </row> + + <row> + <entry>Zeile 2, Spalte 1</entry> + <entry>Zeile 2, Spalte 2</entry> + </row> + </tbody> + </tgroup> +</informaltable>]]></programlisting> + + <para>Darstellung:</para> + + <informaltable pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Spaltenüberschrift 1</entry> + <entry>Spaltenüberschrift 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Zeile 1, Spalte 1</entry> + <entry>Zeile 1, Spalte 2</entry> + </row> + + <row> + <entry>Zeile 2, Spalte 1</entry> + <entry>Zeile 2, Spalte 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + + <para>Verwenden Sie stets das Attribut <literal>pgwide</literal> + mit dem Wert <literal>1</literal>, wenn Sie das Element + <sgmltag>informaltable</sgmltag> benutzen. Ein Bug des + Internet Explorers verhindert ansonsten die korrekte + Darstellung dieser Tabellen.</para> + + <para>Soll die Tabelle keinen Rand haben, kann das Attribut + <literal>frame</literal> mit dem Wert + <literal>none</literal> dem Element + <sgmltag>informaltable</sgmltag> hinzugefügt werden + (<literal><informaltable frame="none"></literal>)).</para> + + <example> + <title>Tabelle mit Attribut + <literal>frame="none"</literal></title> + + <para>Darstellung:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Spaltenüberschrift 1</entry> + <entry>Spaltenüberschrift 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Zeile 1, Spalte 1</entry> + <entry>Zeile 1, Spalte 2</entry> + </row> + + <row> + <entry>Zeile 2, Spalte 1</entry> + <entry>Zeile 2, Spalte 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + </sect3> + + <sect3> + <title>Beispiele für den Leser</title> + + <para>Oft gilt es, für dem Benutzer Beispiele + zu geben, die er dann selber nachvollziehen soll. Meist + handelt es sich dabei um interaktive Dialoge zwischen Mensch + und Maschine: Der Benutzer gibt einen Befehl ein und + erhält eine Antwort vom System. Ein Satz + von speziellen Elementen und Entitäten unterstützt + den Autor bei der Auszeichnung solcher Textstellen:</para> + + <variablelist> + <varlistentry> + <term><sgmltag>screen</sgmltag></term> + + <listitem> + <para>Gedacht zur Auszeichnung von Bildschirminhalten. + Im Unterschied zu anderen Elementen werden Leerzeichen + innerhalb des Elementes <sgmltag>screen</sgmltag> + unverändert übernommen.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>prompt</sgmltag>, + <literal>&prompt.root;</literal> und + <literal>&prompt.user;</literal></term> + + <listitem> + <para>Eingabeaufforderungen des Rechners + (Betriebssysten, Shell oder Anwendung) sind ein häufig + auftretender Teil dessen, was der Benutzer auf dem + Bildschirm zu sehen bekommt. Sie sollten mit + <sgmltag>prompt</sgmltag> ausgezeichnet werden.</para> + + <para>Ein Spezialfall sind die beiden + Eingabeaufforderungen der Shell für normale + Benutzer und den Superuser <username>root</username>. + Jedesmal wenn auf eine von diesen beiden Nutzerrollen + hingewiesen werden soll, sollte entweder + <literal>&prompt.root;</literal> oder + <literal>&prompt.user;</literal> eingesetzt + werden. Beide Entitäten können auch + außerhalb von <sgmltag>screen</sgmltag> + verwendet werden.</para> + + <note> + <para><literal>&prompt.root;</literal> und + <literal>&prompt.user;</literal> sind + FreeBSD-spezifische Erweiterungen der DocBook DTD + und nicht in der originalen DocBook DTD + enthalten.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>userinput</sgmltag></term> + + <listitem> + <para>Das Element <sgmltag>userinput</sgmltag> ist + für die Auszeichnung von Benutzereingaben + gedacht.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag> + und <sgmltag>userinput</sgmltag></title> + + <programlisting><![CDATA[<screen>&prompt.user; <userinput>ls -1</userinput> +foo1 +foo2 +foo3 +&prompt.user; <userinput>ls -1 | grep foo2</userinput> +foo2 +&prompt.user; <userinput>su</userinput> +<prompt>Password: </prompt> +&prompt.root; <userinput>cat foo2</userinput> +This is the file called 'foo2'</screen>]]></programlisting> + + <para>Darstellung:</para> + + <screen>&prompt.user; <userinput>ls -1</userinput> +foo1 +foo2 +foo3 +&prompt.user; <userinput>ls -1 | grep foo2</userinput> +foo2 +&prompt.user; <userinput>su</userinput> +<prompt>Password: </prompt> +&prompt.root; <userinput>cat foo2</userinput> +This is the file called 'foo2'</screen> + </example> + + <note> + <para>Obgleich der Inhalt der Datei + <filename>foo2</filename> in dem obigen Beispiel angezeigt + wird, sollte dieser nicht mit + <sgmltag>programlisting</sgmltag> ausgezeichnet werden. + Vielmehr sollte <sgmltag>programlisting</sgmltag> einzig + und allein für die Darstellung von Dateifragmenten + außerhalb von Benutzeraktionen gewählt + werden.</para> + </note> + </sect3> + </sect2> + + <sect2> + <title>Flußelemente</title> + + <sect3> + <title>Hervorhebungen</title> + + <para>Wenn es darum geht bestimmte Wörter oder Textstellen + hervorzuheben, sollte dafür das Element + <sgmltag>emphasis</sgmltag> verwendet werden. Das so + ausgezeichnete Text wird dann kursiv oder fett dargestellt; + im Falle einer Sprachausgabe würde es anders betont + werden.</para> + + <para>Im Gegensatz zu den HTML mit seinen Elementen + <sgmltag>b</sgmltag> und <sgmltag>i</sgmltag>, kennt DocBook + keinen Weg, um diese Darstellung zu + ändern<footnote><para>Anmerkung des + Übersetzers: Hier sollte man sich noch einmal ins + Gedächtnis rufen, dass mittels der DocBook DTD nur + Inhalte ausgezeichnet werden und nicht das Layout + bestimmt wird.</para></footnote>. Handelt es sich bei + dem darzustellenden um eine wichtige Information, kann + alternativ <sgmltag>important</sgmltag> verwendet + werden.</para> + + <example> + <title>Das Element <sgmltag>emphasis</sgmltag></title> + + <programlisting><![CDATA[<para>FreeBSD ist zweifelslos <emphasis>das</emphasis> führende + Unix-artige Bestriebssystem für die Intel-Plattform.</para>]]></programlisting> + + <para>Darstellung:</para> + + <para>FreeBSD ist zweifelslos <emphasis>das</emphasis> führende + Unix-artige Bestriebssystem für die Intel-Plattform.</para> + + </example> + </sect3> + + <sect3> + <title>Zitate</title> + + <para>Um einen Auszug aus einer anderen Quelle zu zitieren + oder kenntlich zu machen, dass eine bestimmte Wendung + im übertragenen Sinne zu verstehen ist, kann der + betreffende Text mit Hilfe des Elementes + <sgmltag>quote</sgmltag> ausgezeichnet werden. Innerhalb von + <sgmltag>quote</sgmltag> können die meisten der + normalerweise zur Verfügung stehenden Elemente genutzt + werden.</para> + + <example> + <title>Richtig zitieren</title> + + <programlisting><![CDATA[<para>Es sollte immer sichergestellt werden, dass die Suche die Grenzen + zwischen <quote>lokaler und öffentlicher Administration</quote> + (RFC 1535) einhält.</para>]]></programlisting> + + <para>Darstellung:</para> + + <para>Es sollte immer sichergestellt werden, das die Suche + die Grenzen zwischen <quote>lokaler und öffentlicher + Administration</quote> (RFC 1535) einhält.</para> + + </example> + </sect3> + + <sect3> + <title>Tasten, Maustasten und Tastenkombinationen</title> + + <para>Das Element <sgmltag>keycap</sgmltag> beschreibt + eine bestimmte Taste der Tastatur. + Für die Auszeichnung von Maustasten + steht analog das Element <sgmltag>mousebutton</sgmltag> zur + Verfügung. Mit Hilfe von <sgmltag>keycombo</sgmltag> + können beliebige Tasten- und Maustastenkombinationen + beschrieben werden.</para> + + <para>Das Element <sgmltag>keycombo</sgmltag> besitzt ein + Attribut <literal>action</literal>, dem einer der Werte + <literal>click</literal>, <literal>double-click</literal>, + <literal>other</literal>, <literal>press</literal>, + <literal>seq</literal> oder <literal>simul</literal> + zugewiesen werden kann. Die letzten beiden Werte deuten an, + dass die genannte Kombination nacheinander oder + gleichzeitig gedrückt werden soll. Die Stylesheets + fügen zwischen die einzelnen Unterelemente von + <sgmltag>keycombo</sgmltag> <quote>+</quote>-Zeichen + ein.</para> + + + <example> + <title>Tasten, Maustasten und Tastenkombinationen</title> + + <para>Diese Eingaben zeichnen Sie wie folgt aus:</para> + + <programlisting><![CDATA[<para>Mit der Tastenkombination <keycombo action="simul"><keycap>Alt</keycap> + <keycap>F1</keycap></keycombo> kann auf die zweite virtuelle Konsole + umgeschaltet werden.</para> + +<para>Um <command>vi</command> zu beenden, ohne die Änderungen zu + speichern, muss <keycombo action="seq"><keycap>Esc</keycap> + <keycap>:</keycap><keycap>q</keycap><keycap>!</keycap> + </keycombo> eingegeben werden.</para> + +<para>Der Fenstermanager ist so konfiguriert, dass mittels + <keycombo action="simul"><keycap>Alt</keycap> + <mousebutton>rechter Maustaste</mousebutton> </keycombo> + Fenster verschoben werden können.</para>]]></programlisting> + + <para>Darstellung:</para> + + <para>Mit der Tastenkombination <keycombo + action="simul"><keycap>Alt</keycap> + <keycap>F1</keycap></keycombo> kann auf die zweite + virtuelle Konsole umgeschaltet werden.</para> + + <para>Um <command>vi</command> zu beenden, ohne die + Änderungen zu speichern, muss <keycombo + action="seq"><keycap>Esc</keycap> + <keycap>:</keycap><keycap>q</keycap><keycap>!</keycap> + </keycombo> eingegeben werden.</para> + + <para>Der Fenstermanager ist so konfiguriert, dass mittels + <keycombo action="simul"><keycap>Alt</keycap> + <mousebutton>rechter Maustaste</mousebutton> + </keycombo> + Fenster verschoben werden können.</para> + </example> + </sect3> + + <sect3> + <title>Anwendungen, Befehle, Optionen und Hilfeseiten</title> + + <para>Oft besteht die Notwendigkeit auf bestimmte Anwendungen + und Befehle zu verweisen. Der Unterschied zwischen einer + Anwendung und einem Befehl liegt darin, dass eine + Anwendung ein einzelnes oder eine Gruppe von Programmen ist, + mit denen eine bestimmte Aufgabe erledigt werden kann. Ein + Befehl hingegen ist der Name eines Programmes, dass der + Benutzer aufrufen kann<footnote><para>Der Befehl + <command>mozilla</command> startet das Programm + <application>mozilla</application>.</para> + </footnote>.</para> + + <para>Desweiteren kann es auch vorkommen, dass die + von einem Programm (in einem bestimmten Fall) + akzeptierten Optionen genannt werden müssen.</para> + + <para>Schlußendlich ist es oft gewünscht, zu einem + Befehl dessen Abschnitt der Manualseiten im + Unix-üblichen Stil <quote>Befehl(Zahl)</quote> + anzugeben.</para> + + <para>Anwendungsnamen können mit <sgmltag>application</sgmltag> + ausgezeichnet werden.</para> + + <para>Befehle können zusammen mit der betreffenden + Hilfeseite über das DocBook-Element + <sgmltag>citerefentry</sgmltag> ausgezeichnet werden. + <sgmltag>citerefentry</sgmltag> muss zwei weitere + Elemente enthalten: <sgmltag>refentrytitle</sgmltag>, + für den Befehlsnamen, und <sgmltag>manvolnum</sgmltag>, + für die Kategorie der Hilfeseite.</para> + + <para>Diese Art auf Befehle zu verweisen kann sehr + ermüdent sein. Daher gibt es einen Satz von + <link linkend="sgml-primer-general-entities">Allgemeinen + Entitäten</link>, der diese Arbeit erleichtert. Er + ist in der Datei + <filename>doc/share/sgml/man-refs.ent</filename> enhalten + und kann über den folgenden Bezeichner eingebunden + werden:</para> + + <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> + + <para>Jede Entität in dieser Datei ist wie folgt aufgebaut: + <literal>&man.<replaceable>Hilfeseite</replaceable>.<replaceable>Kategorie</replaceable>;</literal>.</para> + + <para>Der Anfang eines Dokumentes, das diese Entitäten + einbindet, könnte so aussehen:</para> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; … ]></programlisting> + + <para>Um Befehle innerhalb des Fließtextes auszuzeichen, + kann das Element <sgmltag>command</sgmltag> genutzt werden. + Die Optionen eines Befehles können mit Hilfe von + <sgmltag>option</sgmltag> ausgezeichnet werden.</para> + + <para>Wenn man sich mehrmals hintereinander auf den gleichen + Befehl bezieht, sollte man beim ersten Auftreten die Notation + <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> + verwenden. Für alle folgenden Referenzen sollte hingegen + <sgmltag>command</sgmltag> verwendet werden. Dadurch + verbessert sich das Erscheinungsbild, insbesondere von HTML, + deutlich.</para> + + <para>Die Unterscheidung zwischen <sgmltag>command</sgmltag> + und <sgmltag>application</sgmltag> kann schwer sein, und + manchmal ist die Entscheidung, welches Element das richtige + ist, nicht leicht. Das folgende Beispiel soll diese + Unterscheidung erleichtern.</para> + + <example> + <title>Anwendungen, Befehle und Optionen</title> + + <programlisting><![CDATA[<para><application>Sendmail</application> ist der verbreitetste + UNIX-Mailserver.</para> + +<para><application>Sendmail</application> besteht aus den Programmen + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, &man.mailq.1;, und &man.newaliases.1;.</para> + +<para>Mittels der Option <option>-bp</option> kann + <citerefentry><refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> den Status der Mailwarteschlange ausgeben. + Der Status der Mailwarteschlange kann durch den Befehl + <command>sendmail -bp</command> überprüft werden.</para>]]></programlisting> + + + <para>Darstellung:</para> + + <para><application>Sendmail</application> ist der + verbreitetste UNIX-Mailserver.</para> + + <para><application>Sendmail</application> besteht aus den + Programmen + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, + &man.mailq.1; sowie &man.newaliases.1;.</para> + + <para>Mittels der Option <option>-bp</option> kann + <citerefentry><refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> den Status der Mailwarteschlange ausgeben. + Der Status der Mailwarteschlange kann durch den Befehl + <command>sendmail -bp</command> überprüft + werden.</para> + </example> + + <note> + <para>Die Schreibweise + <literal>&man.<replaceable>Hilfeseite</replaceable>.<replaceable>Kategorie</replaceable>;</literal> + ist leichter lesbar.</para> + </note> + </sect3> + + <sect3> + <title>Dateien, Verzeichnisse und Erweiterungen</title> + + <para>Immer wenn in einem Text der Name einer Datei, eines + Verzeichnisses oder eine Dateierweiterung vorkommt, sollte + die betreffende Stelle mit dem Element + <sgmltag>filename</sgmltag> ausgezeichnet werden.</para> + + <example> + <title>Das Element <sgmltag>filename</sgmltag></title> + + <programlisting><![CDATA[<para>Die SGML-Quellen des + englischen Handbuches befinden sich im Verzeichnis + <filename + class="directory">/usr/doc/en/handbook/</filename>. In + diesem Verzeichnis befindet sich eine Datei + <filename>handbook.xml</filename>. Desweiteren sollte + sich eine Datei mit dem Namen + <filenname>Makefile</filename> zusammen mit mehreren + Dateien mit der Endung <filename>.ent</filename> in diesem + Verzeichnis befinden.</para>]]></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.xml</filename>. Desweiteren sollte + sich eine Datei mit dem Namen + <filename>Makefile</filename> zusammen mit mehreren + Dateien mit der Endung <filename>.ent</filename> in diesem + Verzeichnis befinden.</para> + + </example> + </sect3> + + <sect3> + <title>Portnamen</title> + + <note> + <title>FreeBSD-Erweiterung</title> + + <para>Die hier genannten Elemente sind Bestandteil der + FreeBSD-Erweiterung für DocBook und sind nicht in der + originalen DocBook DTD enthalten.</para> + </note> + + <para>An einigen Stellen ist es notwendig, den Namen eines + Ports aus FreeBSDs Ports-Sammlung in Dokumenten zu verwenden. + In diesem Fall sollte ebenfalls das Element + <sgmltag>filename</sgmltag> eingesetzt werden, dabei aber + dem Element das Attribut <literal>role</literal> mit dem + Wert <literal>package</literal> zugewiesen werden. Da die + Ports-Sammlung an jeder beliebigen Stelle im Dateisystem + installiert werden kann, sollte <sgmltag>filename</sgmltag> + nur die Kategorie und den Namen des Ports enthalten, aber + nicht das Verzeichnis + <filename>/usr/ports</filename>.</para> + + <example> + <title>Portsnamen und das Element <sgmltag>filename</sgmltag></title> + + <programlisting><![CDATA[<para>Wenn Sie Ihr Netz und dessen Datenverkehr analysieren + möchten, dann installieren Sie bitte den Port <filename + role="package">net/ethereal</filename>.</para>]]></programlisting> + + <para>Darstellung:</para> + + <para>Wenn Sie Ihr Netz und dessen Datenverkehr analysieren + möchten, dann installieren Sie bitte den Port <filename + role="package">net/ethereal</filename>.</para> + </example> + </sect3> + + <sect3> + <title>Gerätedateien unterhalb von + <filename>/dev</filename></title> + + <note> + <title>FreeBSD-Erweiterung</title> + + <para>Die hier genannten Elemente sind Bestandteil der + FreeBSD-Erweiterung für DocBook und sind nicht in der + originalen DocBook DTD enthalten.</para> + </note> + + <para>Wird in einem Dokument Bezug auf Gerätedateien + unterhalb von <filename class="directory">dev</filename> + genommen, dann gibt es zwei Möglichkeiten diese + auszuzeichnen. Zum einen kann man sich auf das Gerät + beziehen, so wie es unter <filename>/dev</filename> zu + finden ist, und zum anderen kann man sich auf den + Gerätenamen beziehen, wie es innerhalb des Kerns + verwendet wird. Für letztere Möglichkeit sollte + das Element <sgmltag>devicename</sgmltag> genutzt + werden.</para> + + <para>Allerdings besteht nicht immer diese + Wahlmöglichkeit. Einige Geräte, wie zum Beispiel + Netzwerkkartenm haben keinen Eintrag unter + <filename>/dev</filename> oder werden anders + dargestellt.</para> + + <example> + <title>Gerätenamen per <sgmltag>devicename</sgmltag> + auszeichnen</title> + + <programlisting><![CDATA[<para>Unter FreeBSD wird die serielle Datenübertragung über + <devicename>sio</devicename> abgewickelt, das unterhalb von + <filename>/dev</filename> eine Reihe von Einträgen anlegt. + Zu diesen Einträgen behören beispielsweise + <filename>/dev/ttyd0</filename> und + <filename>/dev/cuaa0</filename>.</para> + + <para>Andererseits erscheinen Geräte wie beispielsweise + <devicename>ed0</devicename> nicht unterhalb von + <filename>/dev</filename>.</para> + + <para>Unter MS-DOS wird das erste Diskettelaufwerk als + <devicename>a:</devicename> bezeichnet. FreeBSD + bezeichnet es als <filename>/dev/fd0</filename>.</para>]]></programlisting> + + <para>Darstellung:</para> + + <para>Unter FreeBSD wird die serielle Datenübertragung + über <devicename>sio</devicename> abgewickelt, das + unterhalb von <filename>/dev</filename> eine Reihe von + Einträgen anlegt. Zu diesen Einträgen + behören beispielsweise + <filename>/dev/ttyd0</filename> und + <filename>/dev/cuaa0</filename>.</para> + + <para>Andererseits erscheinen Geräte wie beispielsweise + <devicename>ed0</devicename> nicht unterhalb von + <filename>/dev</filename>.</para> + + <para>Unter MS-DOS wird das erste Diskettelaufwerk als + <devicename>a:</devicename> bezeichnet. FreeBSD bezeichnet + es als <filename>/dev/fd0</filename>.</para> + + </example> + </sect3> + + <sect3> + <title>Rechner, Domains, IP-Adressen und mehr</title> + + <note> + <title>FreeBSD-Erweiterung</title> + + <para>Die hier genannten Elemente sind Bestandteil der + FreeBSD-Erweiterung für DocBook und sind nicht in der + originalen DocBook DTD enthalten.</para> + </note> + + + <para>Bezeichner für Rechner können in Abhängigkeit + der Bezeichnungsweise auf verschiedene Art und Weise + ausgezeichnet werden. Gemeinsam ist allen, dass sie + das Element <sgmltag>hostid</sgmltag> benutzen. Über das + Attribut <literal>role</literal> wird die Art des Bezeichners + genauer bestimmt.</para> + + <variablelist> + <varlistentry> + <term>Kein Rollenattribut oder + <literal>role="hostname"</literal></term> + + <listitem> + <para>Ohne Rollenattribut stellt der umschlossene Text + einen normlen Rechnernamen wie + <literal>freefall</literal> oder + <literal>wcarchive</literal> dar. Wenn es + gewünscht ist, kann mittels + <literal>role="hostname"</literal> explizit angegeben + werden, dass es sich um einen Rechnernamen + handelt.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="domainname"</literal></term> + + <listitem> + <para>Ein Domainname wie <literal>FreeBSD.org</literal> + oder <literal>ngo.org.uk</literal>. Er enthält keinen + Rechnernamen.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="fqdn"</literal></term> + + <listitem> + <para>Vollqualifizierter Domainname wie + <literal>www.FreeBSD.org</literal>. Enthält sowohl + einen Domainnamen als auch einen Rechnernamen.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="ipaddr"</literal></term> + + <listitem> + <para>Eine IP-Adresse, meistens als durch Doppelpunkte + getrenntes Tupel von vier Zahlen dargestellt.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="ip6addr"</literal></term> + + <listitem> + <para>Eine IPv6-Adresse.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="netmask"</literal></term> + + <listitem> + <para>Eine Netzwerkmaske, dargestellt als ein durch + Doppelpunkte getrenntes Vierzahlentupel, einer Hexzahl + oder als ein <literal>/</literal>, dem eine Zahl + folgt.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="mac"</literal></term> + + <listitem> + <para>Eine MAC-Adresse, dargestellt durch zweistellige + Hexzahlen, die durch Doppelpunkte getrennt + sind.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><literal>role</literal> und + <sgmltag>hostid</sgmltag></title> + + <programlisting><![CDATA[<para>Der lokale Rechner kann immer über den Namen + <hostid>localhost</hostid> angesprochen werden, dem immer + die IP-Adresse + <hostid role="ipaddr">127.0.0.1</hostid> zugeordnet ist.</para> + + <para>Zur Domain <hostid role="domainname">FreeBSD.org</hostid> + gehören verschiedene Rechner, inklusive <hostid + role="fqdn">freefall.FreeBSD.org</hostid> und <hostid + role="fqdn">pointyhat.FreeBSD.org</hostid>.</para> + + <para>Wenn eine IP-Adresse einer Netzwerkkarte zugeordnet wird, + was mit der Hilfe von <command>ifconfig</command> geschieht, + sollte <emphasis>immer</emphasis> die Netzmaske + <hostid role="netmask">255.255.255.255</hostid>, die auch + hexadezimal als <hostid role="netmask">0xffffffff</hostid> + abgegeben werden kann, benutzt werden.</para> + + <para>Die MAC-Adresse ist für jede existierende Netzwerkkarte + auf der Welt eindeutig. Eine typische MAC-Adresse ist + beispielsweise <hostid + role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting> + + <para>Darstellung:</para> + + <para>Der lokale Rechner kann immer über den Namen + <hostid>localhost</hostid> angesprochen werden, dem immer + die IP-Adresse <hostid role="ipaddr">127.0.0.1</hostid> + zugeordnet ist.</para> + + <para>Zur Domain <hostid + role="domainname">FreeBSD.org</hostid> gehören + verschieden Rechner, inklusive <hostid + role="fqdn">freefall.FreeBSD.org</hostid> und <hostid + role="fqdn">bento.FreeBSD.org</hostid>.</para> + + <para>Wenn eine IP-Adresse einer Netzwerkkarte zugeordnet + wird, was mit der Hilfe von <command>ifconfig</command> + geschieht, sollte <emphasis>immer</emphasis> die Netzmaske + <hostid role="netmask">255.255.255.255</hostid>, die auch + hexadezimal als <hostid role="netmask">0xffffffff</hostid> + abgegeben werden kann, benutzt werden.</para> + + <para>Die MAC-Adresse ist für jede existierende + Netzwerkkarte auf der Welt eindeutig. Eine typische + MAC-Adresse ist beispielsweise <hostid + role="mac">08:00:20:87:ef:d0</hostid>.</para> + </example> + </sect3> + + <sect3> + <title>Benutzernamen</title> + + <note> + <title>FreeBSD-Erweiterung</title> + + <para>Die hier genannten Elemente sind Bestandteil der + FreeBSD-Erweiterung für DocBook und sind nicht in der + originalen DocBook DTD enthalten.</para> + </note> + + <para>Namen von Benutzern, wie + <literal>root</literal> oder <literal>bib</literal>, + können mit dem Element <sgmltag>username</sgmltag> + ausgezeichnet werden.</para> + + <example> + <title>Das Element <sgmltag>username</sgmltag></title> + + <programlisting><![CDATA[<para>Für die meisten Administrationsaufgaben müssen + Sie als <username>root</username> angemeldet sein.</para>]]></programlisting> + + <para>Darstellung:</para> + + <para>Für die meisten Administrationsaufgaben müssen Sie als + <username>root</username> angemeldet sein.</para> + + </example> + </sect3> + + <sect3> + <title>Beschreibung von <filename>Makefile</filename>s</title> + + <note> + <title>FreeBSD-Erweiterung</title> + + <para>Die hier genannten Elemente sind Bestandteil der + FreeBSD-Erweiterung für DocBook und sind nicht in der + originalen DocBook DTD enthalten.</para> + </note> + + <para>Zur Beschreibung von Teilen einer Makedatei stehen die + beiden Elemente <sgmltag>marketarget</sgmltag> und + <sgmltag>makevar</sgmltag> zur Verfügung. + <sgmltag>maketarget</sgmltag> bezeichnet ein Ziel eines + <filename>Makefile</filename>s, das als Parameter beim + Aufruf von <command>make</command> angegeben werden kann. + <sgmltag>makevar</sgmltag> hingegen bezeichnet eine + Variable, die entweder in einem + <filename>Makefile</filename> definiert oder + <command>make</command> auf der Befehlszeile übergeben + werden kann, um so den Bauprozess zu beeinflussen.</para> + + <example> + <title><sgmltag>maketarget</sgmltag> und + <sgmltag>makevar</sgmltag></title> + + <programlisting><![CDATA[<para>Zwei übliche Ziele in einem <filename>Makefile</filename> + sind <maketarget>all</maketarget> und + <maketarget>clean</maketarget>.</para> + +<para>Üblicherweise wird, wenn das Ziel <maketarget>all</maketarget> + aufgerufen wird, die gesamte Anwendung neu erstellt. Der Aufruf + des Zieles <maketarget>clean</maketarget> veranlaßt das + Löschen aller temporären Dateien (zum Beispiel + <filename>.o</filename>), die während der Übersetzung erzeugt + wurden.</para> + +<para>Das genaue Verhalten von <maketarget>clean</maketarget> + kann von einer Reihe von Variablen beeinflußt werden. + Stellvertretend seien hier <makevar>CLOBBER</makevar> und + <makevar>RECURSE</makevar> genannt.</para>]]></programlisting> + + <para>Darstellung:</para> + + <para>Zwei übliche Ziele in einem + <filename>Makefile</filename> sind + <maketarget>all</maketarget> und + <maketarget>clean</maketarget>.</para> + + <para>Üblicherweise wird, wenn das Ziel + <maketarget>all</maketarget> aufgerufen wird, die gesamte + Anwendung neu erstellt. Der Aufruf des Zieles + <maketarget>clean</maketarget> veranlaßt das + Löschen aller temporären Dateien (zum Beispiel + <filename>.o</filename>), die während der + Übersetzung erzeugt wurden.</para> + + <para>Das genaue Verhalten von + <maketarget>clean</maketarget> kann von einer Reihe von + Variablen beeinflußt werden. Stellvertretend seien + hier <makevar>CLOBBER</makevar> und + <makevar>RECURSE</makevar> genannt.</para> + </example> + </sect3> + + <sect3> + <title>Text buchstabengetreu übernehmen</title> + + <para>Für das Handbuch ist es oft notwendig, Textausschnitte + buchstabengetreu darzustellen. Hierbei kann es sich um Texte + handeln, die aus einer anderen Datei stammen oder die der + Leser eins-zu-eins aus dem Handbuch kopieren können + soll.</para> + + <para>In einigen Fällen ist zu diesem Zwecke + <sgmltag>programlisting</sgmltag> ausreichend, jedoch nicht + immer. So ist <sgmltag>programlisting</sgmltag> zum Beispiel + nicht einsetzbar, wenn es darum geht, einen Auszug aus einer + Datei innerhalb eines Absatzes einzufügen. In solchen Fällen + sollte das Element <sgmltag>literal</sgmltag> zum Einsatz + kommen.</para> + + <example> + <title><sgmltag>literal</sgmltag></title> + + <programlisting><![CDATA[<para>Die Zeile <literal>maxusers 10</literal> in der + Kernelkonfigurationsdatei beeinflußt die Größe vieler + Systemtabellen und kann als ungefähr als Richtwert dafür + gelten, wie viele paralle Anmeldungen das System handhaben + kann.</para>]]></programlisting> + + <para>Darstellung:</para> + + <para>Die Zeile <literal>maxusers 10</literal> in der + Kernelkonfigurationsdatei beeinflußt die Größe vieler + Systemtabellen und kann als ungefähr als Richtwert dafür + gelten, wie viele paralle Anmeldungen das System handhaben + kann.</para> + </example> + </sect3> + + <sect3> + <title>Benutzerspezifische Eingaben darstellen</title> + + <!--@todo Klingt ein wenig kompiliziert. + Oliver Fischer --> + + <para>Es kommt oft vor, dass der Leser Beispiele, + Dateinamen oder Kommandozeilen verändern muss. + Für einen solchen Anwendungsfall + ist das Element <sgmltag>replaceable</sgmltag> gedacht. Es + kann <emphasis>innerhalb</emphasis> von anderen Elementen + genutzt werden, um die Teile auszuzeichnen, die es zu + ersetzen gilt.</para> + + <example> + <title>Das Element <sgmltag>replaceable</sgmltag></title> + + <programlisting><![CDATA[<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting> + + <para>Darstellung:</para> + + <informalexample> + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> + </informalexample> + + <para>Dieses Beispiel zeigt, dass nur der Text mit + <sgmltag>replaceable</sgmltag> umschlossen werden soll, + den der Benutzer einzusetzen hat. Sämtlicher anderer + Text sollte wie üblich ausgezeichnet werden.</para> + + <programlisting><![CDATA[<para>Die Zeile + <literal>maxusers <replaceable>n</replaceable></literal> + in der Kernelkonfigurationsdatei bestimmt die Größe vieler Systemtabellen + und stellt einen groben Richtwert dafür dar, wie viele gleichzeitige Anmeldungen + das System unterstützt.</para> + +<para>Für einen Arbeitsplatzrechner stellt <literal>32</literal> einen guten + Wert für <replaceable>n</replaceable> dar.</para>]]></programlisting> + + <para>Darstellung:</para> + + <para>Die Zeile <literal>maxusers + <replaceable>n</replaceable></literal> in der + Kernelkonfigurationsdatei bestimmt die Größe + vieler Systemtabellen und stellt einen groben Richtwert + dafür dar, wie viele gleichzeitige Anmeldungen das + System unterstützt.</para> + + <para>Für einen Arbeitsplatzrechner stellt + <literal>32</literal> einen guten Wert für + <replaceable>n</replaceable> dar.</para> + </example> + </sect3> + + <sect3> + <title>Fehlermeldungen des Systems darstellen</title> + + <para>In manchen Fällen kann es nötig sein, + Fehlermeldungen darzustellen, die von FreeBSD erzeugt werden + können. Für solche Fälle ist das Element + <sgmltag>errorname</sgmltag> vorgesehen.</para> + + <example> + <title>Das Element <sgmltag>errorname</sgmltag></title> + + <programlisting><![CDATA[ <screen><errorname>Panic: cannot mount root</errorname></screen> ]]></programlisting> + + + <para>Darstellung:</para> + + <informalexample> + <screen><errorname>Panic: cannot mount root</errorname></screen> + </informalexample> + </example> + </sect3> + </sect2> + <sect2> + <title>Bilder und Grafiken</title> + + <important> + <para>Die Verwendung von Grafiken innerhalb der Dokumentation + ist momentan noch in einem experimentellen Stadium. Es ist + daher wahrscheinlich, dass sich die hier beschriebenen + Mechanismen noch ändern werden.</para> + + <para>Für die Verwendung von Grafiken ist es notwendig, + den Port <filename + role="package">graphics/ImageMagick</filename> + zusätzlich zu installieren, da er + <emphasis>nicht</emphasis> vom Port <filename + role="package">textproc/docproj</filename> mitinstalliert + wird.</para> + + <para>Das beste Beispiel für den Einsatz von Grafiken ist + der unter + <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> + zu findene Artikel <quote>Design elements of the FreeBSD VM + system</quote>. Falls beim Lesen der folgenden Kapitel + Fragen unbeantwortet oder unklar bleiben, empfiehlt es sich, + die unter dem genannten Verzeichnis befindlichen Dateien zu + studieren und anhand ihrer zu verstehen, wie alles + zusammenhängt. Es empfiehlt sich, den Artikel in + verschiedenen Ausgabeformaten zu erzeugen, da man so sehen + kann, wie die Grafiken in Abhängigkeit vom + Ausgabemedium angeordnet werden.</para> + </important> + + <sect3> + <title>Unterstütze Grafikformate</title> + + <para>Zur Zeit werden nur zwei Grafikformate unterstützt. + Welches von beiden Formaten zum Einsatz kommen sollte, + hängt von der Art der Grafik ab.</para> + + <para>Für Bilder, die vorrangig Vektorelemente wie + Netzwerkdiagramme, Zeitlinien und ähnliches beinhalten, + sollte Encapsulated Postscript als Format gewählt + werden. Wichtig ist es in diesem Fall, dass die + Grafikdatei die Endung <filename>.eps</filename> hat. + Für Bitmapgrafiken, wie zum Beispiel Bildschirmfotos, + steht das Portable Network Grafic Format zur + Verfügung. In diesem Fall, sollte die Grafikdatei immer + die Endung <filename>.png</filename> haben.</para> + + <para>In das Subversion-Repository sollten <emphasis>nur</emphasis> + Grafiken in diesen beiden Formaten übernommen + werden.</para> + + <para>Es sollte darauf sehr darauf geachtet werden, das + richtige Format für das richtige Bild zu wählen. + Erwartungsgemäß wird es Dokumente geben, die eine + Mischung aus PNG- und EPS-Grafiken enthalten. In solchen + Fällen, stellen die Makedateien die Verwendung des + richtigen Formats in Abhängigkeit vom Ausgabeformat + sicher. <emphasis>Deshalb sollte die gleiche Grafik niemals + in zwei unterschiedlichen Formaten in das CVS-Archiv + übernommen werden</emphasis>.</para> + + <important> + <para>Es ist absehbar, dass das Dokumentationsprojekt + in Zukunft das Scalable Vector Graphic-Format (SVG) als + Standardformat für Vektorgrafiken übernehmen + wird. Zum jetzigen Zeitpunkt ist dieser Wechsel noch nicht + möglich, da der Stand der jetzigen SVG-Anwendungen + noch nicht den dafür notwendigen Erfordernissen + entspricht.</para> + </important> + + </sect3> + + <sect3> + <title>DocBook-Elemente für den Grafikeinsatz</title> + + <para>Das Auszeichnen von Bildern mittels DocBook ist relativ + einfach. Zuerst wird ein + <sgmltag>mediaobject</sgmltag>-Element eingefügt, das + als Container für medienspezifische Elemente fungieren + kann. Für die Zwecke des FDPs sind das die Elemente + <sgmltag>imageobject</sgmltag> und + <sgmltag>textobject</sgmltag>.</para> + + <para>In das <sgmltag>mediaobject</sgmltag>-Element sollten + ein Element vom Typ <sgmltag>imageobject</sgmltag> und zwei + <sgmltag>textobject</sgmltag>-Elemente eingefügt + werden. Das <sgmltag>imageobject</sgmltag>-Element verweist + auf die eigentliche Grafikdatei. Dabei ist allerdings nur + der Dateipfad ohne Erweiterung anzugegeben. Die + <sgmltag>textobject</sgmltag>-Elemente werden dafür + genutzt, Texte aufzunehmen, die dem Leser anstelle des + Bildes oder zusammen mit dem Bild angezeigt werden.</para> + + <para>Dies kann unter zwei Umständen geschehen:</para> + + <itemizedlist> + <listitem> + <para>Wenn ein Dokument als HTML-Datei durch einem Browser + angezeigt wird. In diesem Falle muss jeder Grafik + ein Alternativtext zugeordnet werden, der dem Leser + angezeigt werden kann. Meist ist das notwendig, wenn der + Browser die Grafik noch nicht geladen hat oder wenn der + Benutzer den Mauszeiger über die Grafik + führt.</para> + </listitem> + + <listitem> + <para>Wenn das Dokument als Textdatei gelesen wird. Da in + einer Textdatei keine Grafiken angezeigt werden können, + sollte es für die Grafik eine Textentsprechung geben, + die alternativ angezeigt werden kann.</para> + </listitem> + </itemizedlist> + + <para>Das folgende Beispiel soll das bisher geschriebene + illustrieren. Angenommen es liegt eine einzubindene Grafik + in der Datei <filename>bild1</filename> vor, die die + Darstellung eines As in einem Rechteck enthält. Die + ASCII-Alternative könnte so ausgezeichnet werden:</para> + + <programlisting><mediaobject> + <imageobject> + <imagedata fileref="bild1"> <co id="co-image-ext"/> + </imageobject> + <textobject> + <literallayout class="monospaced">+ - - - - - - - - - - - - - - -+ <co id="co-image-literal"/> +| A | ++- - - - - - - - - - - - - - -+</literallayout> + </textobject> + <textobject> + <phrase>Ein Bild</phrase> <co id="co-image-phrase"/> + </textobject> +</mediaobject></programlisting> + + <calloutlist> + <callout arearefs="co-image-ext"> + <para>Innerhalb vom Element <sgmltag>imageobject</sgmltag> + befindet sich ein Element <sgmltag>imagedata</sgmltag>, + welches mit Hilfe des Attributes + <literal>fileref</literal> den Namen der Grafikdatei + (ohne Erweiterung) angibt. Die Bestimmung der + Dateierweiterung wird von den Stylesheets + übernommen.</para> + </callout> + + <callout arearefs="co-image-literal"> + <para>Das erste <sgmltag>textobject</sgmltag>-Element + enthält ein <sgmltag>literallayout</sgmltag>-Element, + dessen Attribut <literal>class</literal> den Wert + <literal>monospaced</literal> zugewiesen bekommt. Der + Inhalt dieses Elements wird genutzt, wenn das Dokument + in Textform ausgegeben wird. An dieser Stelle hat der + Autor die Möglichkeit seine + <quote>Textzeichenkünste</quote> unter Beweis zu + stellen.</para> + + <para>Wichtig ist, dass die erste und die letzte + Zeile sich gleichauf mit dem öffenden und dem + schließenden Tag befindet. Dadurch wird + sichergestellt, dass keine unnötigen + Leerzeichen in die Ausgabe aufgenommen werden.</para> + </callout> + + <callout arearefs="co-image-phrase"> + <para>Das zweite <sgmltag>textobject</sgmltag>-Element + sollte lediglich ein <sgmltag>phrase</sgmltag>-Element + enthalten. Wird das Dokument nach HTML konvertiert, wird + dessen Inhalt für das Attribut + <literal>alt</literal> des <sgmltag>img</sgmltag>-Tags + verwendet.</para> + </callout> + </calloutlist> + </sect3> + + <sect3> + <title>Die <filename>Makefile</filename>-Einträge</title> + + <para>Alle in einem Dokument verwendeten Grafiken müssen in + dem zugehörigen Makefile in der Variable + <makevar>IMAGES</makevar> enthalten sein. + <makevar>IMAGES</makevar> sollte immer die Namen der + <emphasis>Quellgrafiken</emphasis> enthalten. Werden in + einem Dokument beispielsweise die drei Grafiken + <filename>bild1.eps</filename>, + <filename>bild2.png</filename> und + <filename>bild3.png</filename> referenziert, sollte das + <filename>Makefile</filename> die folgende Zeile + enthalten:</para> + + <programlisting>… +IMAGES= bild1.eps bild2.png bild3.png +…</programlisting> + + <para>Eine andere Möglichkeit wäre:</para> + + <programlisting>… +IMAGES= bild1.eps +IMAGES+= bild2.png +IMAGES+= bild3.png +…</programlisting> + + + <para>Es kann nicht oft genug betont werden: Welche + Grafikdateien für das zu erzeugende Dokument benötigt + werden, wird von dem Makefiles bestimmt. + <makevar>IMAGES</makevar> darf nur die Originaldateien + enthalten.</para> + </sect3> + + <sect3> + <title>Grafiken und Kapitel in Unterverzeichnissen</title> + + <para>Wenn Sie Ihre Dokumentation in mehrere kleine + Dateien aufspalten (siehe + <xref linkend="sgml-primer-include-using-gen-entities"/>), + müssen Sie sorgfältig vorgehen.</para> + + <para>Angenommen es handelt sich um ein Buch, dessen drei + Kapitel in separaten Verzeichnissen angelegt wurden + (<filename>kapitel1/kapitel.xml</filename>, + <filename>kapitel2/kapitel.xml</filename> und + <filename>kapitel3/kapitel.xml</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.xml</filename> enthaltene + Kapitel eingebunden werden, sollte dies so erfolgen:</para> + + <programlisting><mediaobject> + <imageobject> + <imagedata fileref="kapitel1/bild1"> <co id="co-image-dir"/> + </imageobject> + + … +</mediaobject></programlisting> + + <calloutlist> + <callout arearefs="co-image-dir"> + <para><literal>fileref</literal> muss den + Datei- und den Verzeichnisnamen enthalten.</para> + </callout> + </calloutlist> + + <para>Das <filename>Makefile</filename> muss dementsprechend + die Zeile + + <programlisting>… +IMAGES= kapitel1/bild1.png +…</programlisting> + + enthalten.</para> + + <para>Wird dies beachtet, sollte es zu keinen Problemen + kommen.</para> + </sect3> + </sect2> + + <sect2> + <title>Querverweise</title> + + <note> + <para>Querverweise sind auch Flußelemente.</para> + </note> + + <sect3> + <title>Querverweise innerhalb eines Dokumentes</title> + + + <para>Um innerhalb eines Dokumentes Verweise anzulegen, muss + angegeben werden, von welcher Textstelle aus wohin verwiesen + werden soll.</para> + + <para>Jedes DocBook-Element besitzt ein Attribut + <literal>id</literal>, über das seinem Element ein + eindeutiger Bezeichner zugewiesen werden kann.</para> + + + <!-- ?: Mit diesem Absatz bin ich gar nicht zu frieden! --> + <para>In den meisten Fällen werden Querverweise nur zu + Kapiteln gesetzt. Die <sgmltag>chaper</sgmltag>- und + <sgmltag>sect*</sgmltag>-Elemente sollten aus diesem Grunde + ein gesetztes <literal>id</literal>-Attribut + besitzen.</para> + + <example> + <title><sgmltag>chapter</sgmltag> und <sgmltag>section</sgmltag> + mit dem Attribut <literal>id</literal></title> + <!--<title><literal>id on chapters and sections</literal></title>--> + + <programlisting><![CDATA[<chapter id="kapitel1"> + <title>Einführung</title> + + <para>Das ist eine Einführung. Sie enthält ein Unterkapitel, das + ebenfalls einen eigenen Bezeichner hat.</para> + + <sect1 id="kapitel1-unterkapitel1"> + <title>Unterkapitel 1</title> + + <para>Das ist ein Unterkapitel.</para> + </sect1> +</chapter>]]></programlisting> + </example> + + <para>Als Wert für das Attribut <literal>id</literal> + sollte immer ein selbsterklärender Bezeichner gewählt + werden. Zudem ist es notwendig, dass dieser Bezeichner + innerhalb des Dokumentes eindeutig ist. Im obigen Beispiel + wurde der Bezeichner für das Unterkapitel gebildet, + indem der Bezeichner des übergeordneten Kapitels um den + Titel des Unterkapitels erweitert wurde. Diese + Vorgehensweise hilft sicherzustellen, dass Bezeichner + eindeutig sind und bleiben.</para> + + <para>Manchmal soll jedoch nicht auf den Anfang eines Kapitels + verwiesen werden, sondern zum Beispiel auf eine Stelle in + einem Absatz oder auf ein bestimmtes Beispiel. In solchen + Fällen kann an der Stelle, auf die verwiesen werden + soll, das Element <sgmltag>anchor</sgmltag> mit gesetztem + Attribut <literal>id</literal> eingefügt werden. + <sgmltag>anchor</sgmltag> kann selber keinen weiteren Inhalt + aufnehmen.</para> + + <example> + <title>Querverweise und das Element + <sgmltag>anchor</sgmltag></title> + + <programlisting><![CDATA[<para>Dieser Absatz enthält ein + <anchor id="absatz1"/>Ziel für Querverweise, was jedoch keine + Auswirkung auf dessen Darstellung hat.</para>]]></programlisting> + </example> + + <para>Zum Anlegen des eigentlichen Querverweises selbst kann + eines der beiden Elemente <sgmltag>xref</sgmltag> oder + <sgmltag>link</sgmltag> genutzt werden. Beide besitzen das + Attribut <literal>linkend</literal>, dem der + <literal>id</literal>-Wert des Verweiszieles zugewiesen + wird. Ob sich das Ziel vor oder nach dem Verweis befindet, + spielt keine Rolle.</para> + + <para><sgmltag>xref</sgmltag> und <sgmltag>link</sgmltag> + unterscheiden sich jedoch hinsichtlich der Art und Weise, + auf die der Text erzeugt wird, auf dem der Querverweis + liegt. Kommt <sgmltag>xref</sgmltag> zum Einsatz, hat der + Autor keine Kontrolle darüber – der Text wird + automatisch für ihn erzeugt.</para> + + + <example> + <title>Einsatz von <sgmltag>xref</sgmltag></title> + + <!-- @todo Das englische Original sollte um + einen Link zu dem Beispiel erweitert werden. --> + <para>Für dieses Beispiel wird davon ausgegangen, dass sich + folgendes Textfragment irgendwo innerhalb eines Dokumentes + auftaucht, dass das vorherige + <literal>id</literal>-Beispiel enthält.</para> + + + <programlisting><![CDATA[<para>Weitere Informationen gibt + es im <xref linkend="kapitel1"/>.</para> + +<para>Genauere Informationen können im + <xref linkend="kapitel1-unterkapitel1"/> gefunden werden.</para>]]></programlisting> + + <para>Der Verweistext wird automatisch von den Stylesheets + erzeugt und so hervorgehoben, dass ersichtlich ist, + dass es sich bei dem Text um einen Verweis + handelt.</para> + + <blockquote> + <para>Weitere Informationen können in der + <emphasis>Einführung</emphasis> gefunden + werden.</para> + + <para>Genauere Informationen können im + <emphasis>Unterkapitel 1</emphasis> gefunden + werden.</para> + </blockquote> + </example> + + <para>Der Text, auf dem der HTML-Link für den Querverweis + liegt, wurde von den Kapitelüberschriften + übernommen.</para> + + <note> + <para>Das bedeutet, dass es <emphasis>nicht + möglich</emphasis> ist, mit der Hilfe von + <sgmltag>xref</sgmltag> einen Querverweis zu einer mit + <sgmltag>anchor</sgmltag> gekennzeichneten Stelle + anzulegen. Da <sgmltag>anchor</sgmltag> keinen Inhalt + aufnehmen kann, können die Stylesheets nicht + automatisch einen Text für den Verweis + erzeugen.</para> + </note> + + <para>Möchte man selber den für den Verweis + benutzten Text bestimmen können, sollte das Element + <sgmltag>link</sgmltag> verwendet werden. Im Gegensatz zu + <sgmltag>xref</sgmltag> kann <sgmltag>link</sgmltag> Inhalt + aufnehmen, der dann für den Verweis verwendet + wird.</para> + + + <example> + <title><sgmltag>link</sgmltag> beutzen</title> + + <para>Für dieses Beispiel wird davon ausgegangen, dass + es sich in dem Dokument befindet, das auch + das <literal>id</literal>-Beispiel enthält.</para> + + <programlisting><![CDATA[<para>Weitere Informationen können + im <link linkend="kapitel1">ersten Kapitel</link> gefunden + werden.</para> + +<para>Genauere Informationen können in + <link linkend="kapitel1-unterkapitel1">diesem</link> Kapitel + gefunden werden.</para>]]></programlisting> + + <para>Aus diesem SGML-Fragment würden die Stylesheets + folgendes generieren (der hervorgehobene Text deutet den + erzeugten Verweis an):</para> + + <blockquote> + <para>Weitere Informationen können im <emphasis>ersten + Kapitel</emphasis> gefunden werden.</para> + + <para>Genauere Informationen können in + <emphasis>diesem</emphasis> Kapitel gefunden + werden.</para> + </blockquote> + </example> + + <note> + <para>Das letzte Beispiel ist schlecht. Es sollten niemals + Wörter wie <quote>dieses</quote> oder + <quote>hier</quote> als Linktext benutzt werden. Solche + Wörter zwingen den Leser dazu, den Kontext des + Verweises zu lesen, um zu verstehen, wohin der Verweis + führt.</para> + </note> + + <note> + <para>Mit dem Element <sgmltag>link</sgmltag> + <emphasis>kann</emphasis> auf mit + <sgmltag>anchor</sgmltag> gekennzeichnete Stellen im + Dokument verwiesen werden, da der Inhalt von + <sgmltag>link</sgmltag> als Text für den Querverweise + genutzt wird.</para> + </note> + </sect3> + + <sect3> + <title>Verweise auf Dokumente im WWW</title> + + <para>Das Anlegen von Verweisen auf externe Dokumente ist + wesentlich einfacher – solange die URL des zu + referenzierenden Dokumentes bekannt ist. Um von einem + bestimmten Textabschnitt auf das gewünschte externe + Dokument zu verweisen, muss die jeweilige Stelle mit + dem Element <sgmltag>ulink</sgmltag> ausgezeichnet werden. + Mittels des Attributes <literal>url</literal> kann die + Adresse des Zieldokumentes angegeben werden. Bei der + Umformung des Quelldokumentes in die verschiedenen + Ausgabeformate wird der sich zwischen Start- und Endtag + befindliche Text für den Verweis übernommen, den + der Leser aufrufen kann.</para> + + + <example> + <title>Verweise mit <sgmltag>ulink</sgmltag></title> + + <!-- @todo Welchen Fall erforder anstatt? --> + <programlisting><![CDATA[<para>Natürlich ist es möglich, anstatt diesen Text + weiterzulesen, sofort die + <ulink url="&url.base;/de/index.html">FreeBSD-Homepage</ulink> + aufzurufen.<para>]]></programlisting> + + <para>Darstellung:</para> + + <para>Natürlich ist es möglich, anstatt diesen Text + weiterzulesen, sofort die <ulink + url="&url.base;/de/index.html">FreeBSD-Homepage</ulink> + aufzurufen.</para> + + + </example> + </sect3> + </sect2> + </sect1> +</chapter> |