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 | 2888 |
1 files changed, 0 insertions, 2888 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 deleted file mode 100644 index 59653161ea..0000000000 --- a/de_DE.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml +++ /dev/null @@ -1,2888 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- 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: r39632 ---> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xml-markup"> - <title>XML-Dokumente erstellen</title> - - <para>In diesem Kapitel werden die beiden vom FDP eingesetzten - Auszeichnungssprachen XHTML 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 xml:id="xml-markup-xhtml"> - <title>XHTML</title> - - <para>XHTML ist die XML Version der HyperText Markup Language, - der Auszeichnungssprache der Wahl im World Wide Web. - Weitere Informationen zu XHTML finden sich unter - <uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para> - - <para>XHTML kommt bei der Erstellung der Webseiten des - FreeBSD-Projektes zum Einsatz. Für technische Dokumentationen - sollte XHTML jedoch nicht eingesetzt werden, da DocBook eine - größere und bessere Auswahl an Elementen bietet. Folglich - sollte XHTML 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, 4.0 sowie eine XML konforme Version namens - XHTML in seiner neuesten Version XHTML 1.0 (verfügbar als - <emphasis>strict</emphasis> und <emphasis>transitional</emphasis> - Variante.</para> - - <para>Die XHTML-DTDs sind über den Port <package>textproc/xhtml</package> verfügbar und werden - automatisch als Teil des Metaports <package>textproc/docproj</package> - installiert.</para> - - <sect2> - <title>Formale Öffentliche Bezeichner</title> - - <!--@todo Optimierungskandidat. Oliver Fischer --> - <para>Da es mehrere Version von XHTML gibt, existieren auch - mehrere FÖPs, zu denen ein XHTML-Dokument konform - erklärt werden kann. Die Mehrzahl der sich auf der - FreeBSD-Webseite befindenden XHTML-Seiten sind zu der lockeren - Version von XHTML 1.0 konform.</para> - - <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting> - </sect2> - - <sect2> - <title>Die Elemente <tag>head</tag> und - <tag>body</tag></title> - - <para>Ein XHTML-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>) umfasst den eigentlichen - Dokumenteninhalt, der für den Leser bestimmt ist. In einem - XHTML-Dokument werden diese Bereiche über die Elemente - <tag>head</tag> und <tag>body</tag> - voneinander abgegrenzt. Beide sind Kinder des Wurzelelementes - <tag>html</tag>.</para> - - <example> - <title>Die Struktur eines XHTML-Dokumentes</title> - - <programlisting><html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title><replaceable>Der Dokumententitel</replaceable></title> - </head> - - <body> - - … - - </body> -</html></programlisting> - </example> - </sect2> - - <sect2> - <title>Blockelemente</title> - - <sect3> - <title>Überschriften</title> - - <para>XHTML kennt sechs verschiedene Elemente, mit denen - Überschriften ausgezeichnet werden können. Das bekannteste - Element ist <tag>h1</tag>, das sich am Anfang der - Überschriftenhierarchie befindet. <tag>h1</tag> - folgen die Überschriftenelemente <tag>h2</tag> bis - <tag>h6</tag>. Der Inhalt von - <tag>h<replaceable>N</replaceable></tag> stellt den - Text der Überschrift dar.</para> - - <example> - <title><tag>h1</tag>, <tag>h2</tag>…</title> - - <para>Fügen Sie in eine der existierenden Übungsdateien folgendes ein:</para> - - <programlisting><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 XHTML-Seite sollte immer nur eine Überschrift - <tag>h1</tag> haben. Dieser Überschrift können - beliebig viele Kapitel mit einer Überschrift - <tag>h2</tag> folgen, die selbst wiederum eine - beliebige Anzahl von Kapiteln mit einer Überschrift - <tag>h3</tag> enthalten können. Diese - Verschachtelung setzt sich bis zu Kapiteln mit einer - <tag>h6</tag>-Ü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><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 XHTML mit Hilfe des Elementes - <tag>p</tag> ausgezeichnet werden.</para> - - <example> - <title>Absätze mit dem Element <tag>p</tag></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 enthalten.</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>XHTML 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 - <tag>ol</tag> (für - <foreignphrase><emphasis>o</emphasis>rdered - <emphasis>l</emphasis>ist</foreignphrase>) ausgezeichnet, - unsortierte Listen mit <tag>ul</tag> (für - <foreignphrase><emphasis>u</emphasis>nordered - <emphasis>l</emphasis>ist</foreignphrase>) und - Definitionslisten mit <tag>dl</tag>.</para> - - - <para>Listenpunkte sortierter und unsortierter Listen werden - mit dem Element <tag>li</tag> ausgezeichnet, - welches Text oder andere Blockelemente enthalten kann. - Begriffe, die in einer Definitionslisten enthalten sind, - werden mit dem Element <tag>dt</tag> (für - <foreignphrase><emphasis>d</emphasis>efinition - <emphasis>t</emphasis>erm</foreignphrase>) ausgezeichnet. - Die Erklärung zu diesem Begriff wird mit Hilfe des Elementes - <tag>dd</tag> (für <foreignphrase>definition - description</foreignphrase>) markiert. So wie - <tag>li</tag>, kann das Element - <tag>dd</tag> ebenfalls andere Blockelemente - aufnehmen.</para> - - <example> - <title>Listen mit <tag>ul</tag> und - <tag>ol</tag> 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 <tag>dl</tag> 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 XHTML-Spezifikation ist dafür das Element - <tag>pre</tag> vorgesehen, welches dafür sorgt, dass - Zeilenumbrüche erhalten bleiben und Leerzeichen nicht - zusammengefasst werden. Browser verwenden für den - Inhalt des Elementes <tag>pre</tag> - üblicherweise eine Fixschrift.</para> - - <example> - <title>Vorformatierten Text mit <tag>pre</tag> 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 XHTML mit Hilfe des Elements - <tag>table</tag> auszeichnen. Eine Tabelle setzt - sich aus einer oder mehreren Zeilen (<tag>tr</tag>) - zusammen, von denen jede mindestens eine Zelle - (<tag>td</tag>) 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 <tag>p</tag> zu umschließen.</para> - - <example> - <title>Einfache Tabelle mit <tag>table</tag></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>XHTML kennt die Möglichkeit, dass sich eine - Zelle mehrere Zeilen und/oder Spalten erstrecken kann. - Sollen beispielsweise mehrere Spalten zusammenfassen werden, - kann dies 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 Tabelle 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> - <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 - <tag>strong</tag> und <tag>em</tag> erreicht - werden. <tag>strong</tag> stellt dabei eine - stärkere Hervorhebung als <tag>em</tag> dar, - wobei mit <tag>strong</tag> ausgezeichnete Elemente - fett und mit <tag>em</tag> ausgezeichnete Elemente - kursiv dargestellt werden. Allerdings ist diese Aussage - nicht verlässlich, da die Darstellung vom Browser - abhängig ist. In der Praxis ist es so, dass Webseiten - nur strukturelle und semantische Informationen enthalten - und Stylesheets später auf diese Informationen - angewendet werden. Beachten Sie also die Semantik und - nicht die Formatierung wenn Sie mit diesen - Tags arbeiten.</para> - - <example> - <title>Text mit <tag>em</tag> und <tag>strong</tag> - 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> - <title>Nicht-proportionale Schrift für Texte</title> - - <para>Der Tag <tag>tt</tag> erlaubt es, - Text in einer schreibmaschinenähnlichen - Schrift darzustellen.</para> - - <example> - <title>Nicht-proportionale Schrift mit - <tag>tt</tag></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> - </sect2> - - <sect2 xml: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 <tag>a</tag> und dessen Attribute <tag role="attribute">href</tag>, 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>XHTML 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 <tag>a</tag> gesetzt werden, nur das anstelle - von <literal>href</literal> das Attribut - <literal>name</literal> gesetzt werden - muss.</para> - - <example> - <title>Anwendung von <literal><a id="..."></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 XHTML-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 xml:id="xml-markup-docbook"> - <title>Die DocBook DTD</title> - - <para>DocBook wurde ursprünglich von HaL Computer Systems und - O'Reilly & Associates als DTD für das Erstellen von - technischen Dokumenten entwickelt - - <footnote><para>Einen kurzen historischen Abriss finden Sie unter - <link xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para> - </footnote>. - - Seit 1998 wird es vom <link xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> - DocBook Technical Committee</link> 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 XHTML.</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 - Elementinhalt folgt. Die informelle Variante hingegen hat - keinen Titel.</para> - </note> - - <para>Die DocBook DTD ist in der Ports-Sammlung im Port <package>textproc/docbook</package> enthalten und wird - bei der Installation des Metaports <package>textproc/docproj</package> automatisch - installiert.</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 (<link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>) - 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.2-Based Extension//EN"</programlisting> - </sect2> - - <sect2 xml: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 <tag>chapter</tag>-Elemente strukturiert - wird. Sollte das noch nicht ausreichend sein, können die - einzelnen Kapitel eines Buches mit Hilfe des Elementes - <tag>part</tag> in Teile aufgespalten werden. Das - Handbuch ist beispielsweise auf diese Weise aufgebaut.</para> - - <para>Kapitel (<tag>chapter</tag>) können weiterhin in - Unterkapitel unterteilt werden. Diese werden durch die - Elemente <tag>sect1</tag> ausgezeichnet. Soll ein - Unterkapitel selbst weitere Unterkapitel enthalten, kann das - über das Element <tag>sect2</tag> geschehen. Diese - Unterteilung kann bis zur Tiefe von fünf Unterkapiteln – - über die Elemente <tag>sect3</tag>, - <tag>sect4</tag> und <tag>sect5</tag> – - 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 einfacher strukturiert - als ein Buch. So kann ein Artikel beispielsweise keine Kapitel - (<tag>chapter</tag>) enthalten. Stattdessen kann der - Inhalt eines Artikels nur durch die schon bekannten - <tag>sect<replaceable>N</replaceable></tag>-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 <link xlink:href="&url.base;/de/docs.html">Tutorien von - FreeBSD</link> sind als Artikel verfasst, während - hingegen die <link xlink:href="&url.books.faq;/index.html">FreeBSD-FAQ</link> und das <link xlink:href="&url.books.handbook;/index.html">FreeBSD-Handbuch</link> als - Bücher verfasst wurden.</para> - - <sect3> - <title>Bücher schreiben</title> - - <para>Der Inhalt eines Buches wird in einem - <tag>book</tag>-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 - <tag>bookinfo</tag>-Element abgelegt werden.</para> - - <example> - <title>Buchvorlage <tag>book</tag> mit - <tag>bookinfo</tag></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 - <tag>article</tag>-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 - <tag>articleinfo</tag>-Element abgelegt - werden.</para> - - <example> - <title>Artikelvorlage <tag>article</tag> mit - <tag>articleinfo</tag></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 - <tag>chapter</tag>-Element angelegt und müssen ein - <tag>title</tag>-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. Neben einem - <tag>title</tag>-Element müssen sie weiteren Inhalt - beinhalten. Falls ein leeres Kapitel benötig wird, kann dies - durch das Einfügen eines leeren Absatzes - (<tag>para</tag>) 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 xml: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 <tag>chapter</tag>-Elemente in Kapitel - unterteilt. Eine weitergehende Untergliederung kann durch - das Anlegen von Unterkapiteln erreicht werden. Im Gegensatz - zu Kapiteln, die durch <tag>chapter</tag>-Elemente - ausgezeichnet werden, erfolgt die Auszeichnung von - Unterkapitel mit dem Element - <tag>sect<replaceable>n</replaceable></tag>. Das - <replaceable>n</replaceable> in Elementnamen trifft eine - Aussage über die Gliederungstiefe, auf der sich das - Unterkapitel befindet. Ein <tag>sect1</tag>-Element - kann mehrere Elemente vom Typ <tag>sect2</tag> - enthalten, die die Unterkapitel der - nächsten Gliederungsebene darstellen. - <tag>sect5</tag> 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 <tag>part</tag> - unterteilen</title> - - <para>In den Fällen, in denen die Unterteilung eines Buches in - Kapitel nicht ausreichend ist, können mehrere - Kapitel mit dem Element <tag>part</tag> 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 (<tag>formalpara</tag>), - normale Absätze (<tag>para</tag>) und einfache - Absätze (<tag>simpara</tag>).</para> - - <para>Normale Absätze und einfache Absätze - unterscheiden sich dadurch, dass innerhalb von - <tag>para</tag> Blockelemente erlaubt sind, - innerhalb von <tag>simpara</tag> hingegen nicht. Es - ist empfehlenswert, <tag>para</tag> den Vorzug - zu geben.</para> - - <example> - <title>Absatz mit <tag>para</tag></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><tag>blockquote</tag></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 <tag>tip</tag> - (für Tipps), <tag>note</tag> (für - Anmerkungen), <tag>warning</tag> (für - Warnungen), <tag>caution</tag> (für besonders - ernstzunehmende Warnungen) und <tag>important</tag> - (für wichtige Anmerkungen) ausgezeichnet werden. Trifft - keines dieser Elemente für die auszuzeichnende Stelle - zu, sollte diese mit dem Element <tag>sidebar</tag> - 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 (<tag>note</tag>) ist eine - Information, die von jedem Leser beachtet werden - sollte.</para> - </listitem> - - <listitem> - <para>Eine wichtige Anmerkung - (<tag>important</tag>) eine Variation einer - Anmerkung.</para> - </listitem> - - <listitem> - <para>Eine Warnung (<tag>warning</tag>) - betrifft einen möglichen Hardwareschaden - oder weist auf eine Gefahr für Leib und Leben - hin.</para> - </listitem> - - <listitem> - <para>Eine besonders ernstzunehmende Warnung - (<tag>caution</tag>) betrifft einen möglichen - Datenverlust oder Softwareschaden.</para> - </listitem> - </itemizedlist> - - <example> - <title><tag>warning</tag></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 <tag>itemizedlist</tag>, - <tag>orderedlist</tag> und - <tag>procedure</tag> 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><tag>itemizedlist</tag> und - <tag>orderedlist</tag> ähneln sehr stark ihren - HTML-Gegenstücken <tag>ul</tag> und - <tag>ol</tag>. Beide Listenarten müssen - mindestens ein Element <tag>listitem</tag> - enthalten. Das <tag>listitem</tag> Element - muss mindestens ein weiteres Blockelement - enthalten.</para> - - <para><tag>procedure</tag> unterscheidet sich ein - wenig von den vorhergehenden. Es enthält - <tag>step</tag>-Elemente, die wiederum - <tag>step</tag>- oder - <tag>substel</tag>-Elemente enthalten können. - Ein <tag>step</tag>-Element kann nur Blockelemente - aufnehmen.</para> - - <example> - <title><tag>itemizedlist</tag>, - <tag>orderedlist</tag> und - <tag>procedure</tag></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 - <tag>programmlisting</tag> zur Verfügung. Im - Gegensatz zu anderen DocBook-Elementen wird der - Elementinhalt von <tag>programmlisting</tag> - <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><tag>programlisting</tag></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 - (<tag>programlisting</tag>, - <tag>literallayout</tag>, …) mit - <tag>co</tag>-Elementen markiert werden, wobei jedes - Element ein eindeutiges <literal>id</literal>-Attribut - besitzen muss. Anschließend sollte ein - <tag>calloutlist</tag>-Element eingefügt werden, - dessen Elemente sich auf die <tag>co</tag>-Elemente - des Beispiels beziehen und die jeweiligen Anmerkungen - enthalten.</para> - - <example> - <title>Das <tag>co</tag>- und das - <tag>calloutlist</tag>-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 xml:id="co-ex-include"/> - -int <co xml:id="co-ex-return"/> -main(void) -{ - printf("Hallo Welt\n"); <co xml: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 - <tag>table</tag>-Element. Dieses Element selbst - beinhaltet mindestens ein Element <tag>tgroup</tag>, - das über ein Attribut die Spaltenanzahl der Tabelle - bestimmt. Innerhalb des Elementes <tag>tgroup</tag> - kann sich ein Element <tag>thead</tag> mit den - Spaltenüberschriften und ein Element - <tag>tbody</tag> mit dem eigentlichen Tabelleninhalt - befinden. Beide Elemente beinhalten - <tag>row</tag>-Elemente, die wiederum - <tag>entry</tag>-Elemente beinhalten. Jedes - <tag>entry</tag>-Element stellt eine einzelne - Tabellenzelle dar.</para> - - <example> - <title>Tabellen mittels <tag>informaltable</tag> - 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 - <tag>informaltable</tag> 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 - <tag>informaltable</tag> 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><tag>screen</tag></term> - - <listitem> - <para>Gedacht zur Auszeichnung von Bildschirminhalten. - Im Unterschied zu anderen Elementen werden Leerzeichen - innerhalb des Elementes <tag>screen</tag> - unverändert übernommen.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><tag>prompt</tag>, - <literal>&prompt.root;</literal> und - <literal>&prompt.user;</literal></term> - - <listitem> - <para>Eingabeaufforderungen des Rechners - (Betriebssystem, Shell oder Anwendung) sind ein häufig - auftretender Teil dessen, was der Benutzer auf dem - Bildschirm zu sehen bekommt. Sie sollten mit - <tag>prompt</tag> ausgezeichnet werden.</para> - - <para>Ein Spezialfall sind die beiden - Eingabeaufforderungen der Shell für normale - Benutzer und den Superuser <systemitem class="username">root</systemitem>. - Jedes mal 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 <tag>screen</tag> - 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><tag>userinput</tag></term> - - <listitem> - <para>Das Element <tag>userinput</tag> ist - für die Auszeichnung von Benutzereingaben - gedacht.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><tag>screen</tag>, <tag>prompt</tag> - und <tag>userinput</tag></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 - <tag>programlisting</tag> ausgezeichnet werden. - Vielmehr sollte <tag>programlisting</tag> 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 - <tag>emphasis</tag> 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 - <tag>b</tag> und <tag>i</tag>, 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 <tag>important</tag> verwendet - werden.</para> - - <example> - <title>Das Element <tag>emphasis</tag></title> - - <programlisting><![CDATA[<para>FreeBSD ist zweifelslos <emphasis>das</emphasis> führende - Unix-artige Betriebssystem 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 - <tag>quote</tag> ausgezeichnet werden. Innerhalb von - <tag>quote</tag> 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 <tag>keycap</tag> beschreibt - eine bestimmte Taste der Tastatur. - Für die Auszeichnung von Maustasten - steht analog das Element <tag>mousebutton</tag> zur - Verfügung. Mit Hilfe von <tag>keycombo</tag> - können beliebige Tasten- und Maustastenkombinationen - beschrieben werden.</para> - - <para>Das Element <tag>keycombo</tag> 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 - <tag>keycombo</tag> <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>Schlussendlich 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 <tag>application</tag> - ausgezeichnet werden.</para> - - <para>Befehle können zusammen mit der betreffenden - Hilfeseite über das DocBook-Element - <tag>citerefentry</tag> ausgezeichnet werden. - <tag>citerefentry</tag> muss zwei weitere - Elemente enthalten: <tag>refentrytitle</tag>, - für den Befehlsnamen, und <tag>manvolnum</tag>, - 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="xml-primer-general-entities">Allgemeinen - Entitäten</link>, der diese Arbeit erleichtert. Er - ist in der Datei - <filename>doc/share/xml/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.Hilfeseite.Kategorie;</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 auszuzeichnen, - kann das Element <tag>command</tag> genutzt werden. - Die Optionen eines Befehles können mit Hilfe von - <tag>option</tag> ausgezeichnet werden.</para> - - <para>Wenn man sich mehrmals hintereinander auf den gleichen - Befehl bezieht, sollte man beim ersten Auftreten die Notation - <literal>&man.command.section;</literal> - verwenden. Für alle folgenden Referenzen sollte hingegen - <tag>command</tag> verwendet werden. Dadurch - verbessert sich das Erscheinungsbild, insbesondere von HTML, - deutlich.</para> - - <para>Die Unterscheidung zwischen <tag>command</tag> - und <tag>application</tag> 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 verbreiteteste - 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.Hilfeseite.Kategorie;</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 - <tag>filename</tag> ausgezeichnet werden.</para> - - <example> - <title>Das Element <tag>filename</tag></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 - <tag>filename</tag> 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 <tag>filename</tag> - nur die Kategorie und den Namen des Ports enthalten, aber - nicht das Verzeichnis - <filename>/usr/ports</filename>.</para> - - <example> - <title>Portsnamen und das Element <tag>filename</tag></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 <package>net/ethereal</package>.</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>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 <tag>devicename</tag> genutzt - werden.</para> - - <para>Allerdings besteht nicht immer diese - Wahlmöglichkeit. Einige Geräte, wie zum Beispiel - Netzwerkkarten haben keinen Eintrag unter - <filename>/dev</filename> oder werden anders - dargestellt.</para> - - <example> - <title>Gerätenamen per <tag>devicename</tag> - 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 gehö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 Diskettenlaufwerk 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 <filename>sio</filename> 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 - <filename>ed0</filename> nicht unterhalb von - <filename>/dev</filename>.</para> - - <para>Unter MS-DOS wird das erste Diskettelaufwerk als - <filename>a:</filename> 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 <tag>hostid</tag> 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 normalen 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 - <tag>hostid</tag></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 - <systemitem>localhost</systemitem> angesprochen werden, dem immer - die IP-Adresse <systemitem class="ipaddress">127.0.0.1</systemitem> - zugeordnet ist.</para> - - <para>Zur Domain <systemitem class="fqdomainname">FreeBSD.org</systemitem> gehören - verschieden Rechner, inklusive <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> und <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</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 - <systemitem class="netmask">255.255.255.255</systemitem>, die auch - hexadezimal als <systemitem class="netmask">0xffffffff</systemitem> - 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 <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</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 <tag>username</tag> - ausgezeichnet werden.</para> - - <example> - <title>Das Element <tag>username</tag></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 - <systemitem class="username">root</systemitem> 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 <tag>marketarget</tag> und - <tag>makevar</tag> zur Verfügung. - <tag>maketarget</tag> bezeichnet ein Ziel eines - <filename>Makefile</filename>s, das als Parameter beim - Aufruf von <command>make</command> angegeben werden kann. - <tag>makevar</tag> 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><tag>maketarget</tag> und - <tag>makevar</tag></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> veranlasst 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 beeinflusst 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 - <buildtarget>all</buildtarget> und - <buildtarget>clean</buildtarget>.</para> - - <para>Üblicherweise wird, wenn das Ziel - <buildtarget>all</buildtarget> aufgerufen wird, die gesamte - Anwendung neu erstellt. Der Aufruf des Zieles - <buildtarget>clean</buildtarget> 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 - <buildtarget>clean</buildtarget> kann von einer Reihe von - Variablen beeinflusst werden. Stellvertretend seien - hier <varname>CLOBBER</varname> und - <varname>RECURSE</varname> 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 - <tag>programlisting</tag> ausreichend, jedoch nicht - immer. So ist <tag>programlisting</tag> 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 <tag>literal</tag> zum Einsatz - kommen.</para> - - <example> - <title><tag>literal</tag></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 parallele 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 <tag>replaceable</tag> 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 <tag>replaceable</tag></title> - - <programlisting><![CDATA[<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting> - - <para>Darstellung:</para> - - <informalexample> - <screen>&prompt.user; <userinput>man command</userinput></screen> - </informalexample> - - <para>Dieses Beispiel zeigt, dass nur der Text mit - <tag>replaceable</tag> 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 - n</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 - <tag>errorname</tag> vorgesehen.</para> - - <example> - <title>Das Element <tag>errorname</tag></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 <package>graphics/ImageMagick</package> - zusätzlich zu installieren, da er - <emphasis>nicht</emphasis> vom Port <package>textproc/docproj</package> 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 - <tag>mediaobject</tag>-Element eingefügt, das - als Container für medienspezifische Elemente fungieren - kann. Für die Zwecke des FDPs sind das die Elemente - <tag>imageobject</tag> und - <tag>textobject</tag>.</para> - - <para>In das <tag>mediaobject</tag>-Element sollten - ein Element vom Typ <tag>imageobject</tag> und zwei - <tag>textobject</tag>-Elemente eingefügt - werden. Das <tag>imageobject</tag>-Element verweist - auf die eigentliche Grafikdatei. Dabei ist allerdings nur - der Dateipfad ohne Erweiterung anzugegeben. Die - <tag>textobject</tag>-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 einzubindende Grafik - in der Datei <filename>bild1.png</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 xml:id="co-image-ext"/> - </imageobject> - <textobject> - <literallayout class="monospaced">+ - - - - - - - - - - - - - - -+ <co xml:id="co-image-literal"/> -| A | -+- - - - - - - - - - - - - - -+</literallayout> - </textobject> - <textobject> - <phrase>Ein Bild</phrase> <co xml:id="co-image-phrase"/> - </textobject> -</mediaobject></programlisting> - - <calloutlist> - <callout arearefs="co-image-ext"> - <para>Innerhalb vom Element <tag>imageobject</tag> - befindet sich ein Element <tag>imagedata</tag>, - 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 <tag>textobject</tag>-Element - enthält ein <tag>literallayout</tag>-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 öffnenden 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 <tag>textobject</tag>-Element - sollte lediglich ein <tag>phrase</tag>-Element - enthalten. Wird das Dokument nach HTML konvertiert, wird - dessen Inhalt für das Attribut - <literal>alt</literal> des <tag>img</tag>-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 - <varname>IMAGES</varname> enthalten sein. - <varname>IMAGES</varname> 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. - <varname>IMAGES</varname> 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="xml-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 <varname>IMAGES</varname> und - in den <tag>imagedata</tag>-Elementen immer auch den - Verzeichnisnamen enthalten.</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 xml: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 <tag>chaper</tag>- und - <tag>sect*</tag>-Elemente sollten aus diesem Grunde - ein gesetztes <literal>id</literal>-Attribut - besitzen.</para> - - <example> - <title><tag>chapter</tag> und <tag>section</tag> - 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 <tag>anchor</tag> mit gesetztem - Attribut <literal>id</literal> eingefügt werden. - <tag>anchor</tag> kann selber keinen weiteren Inhalt - aufnehmen.</para> - - <example> - <title>Querverweise und das Element - <tag>anchor</tag></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 <tag>xref</tag> oder - <tag>link</tag> 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><tag>xref</tag> und <tag>link</tag> - unterscheiden sich jedoch hinsichtlich der Art und Weise, - auf die der Text erzeugt wird, auf dem der Querverweis - liegt. Kommt <tag>xref</tag> zum Einsatz, hat der - Autor keine Kontrolle darüber – der Text wird - automatisch für ihn erzeugt.</para> - - - <example> - <title>Einsatz von <tag>xref</tag></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 - <tag>xref</tag> einen Querverweis zu einer mit - <tag>anchor</tag> gekennzeichneten Stelle - anzulegen. Da <tag>anchor</tag> 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 - <tag>link</tag> verwendet werden. Im Gegensatz zu - <tag>xref</tag> kann <tag>link</tag> Inhalt - aufnehmen, der dann für den Verweis verwendet - wird.</para> - - - <example> - <title><tag>link</tag> 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 <tag>link</tag> - <emphasis>kann</emphasis> auf mit - <tag>anchor</tag> gekennzeichnete Stellen im - Dokument verwiesen werden, da der Inhalt von - <tag>link</tag> 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 <tag>ulink</tag> 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 <tag>ulink</tag></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 <link xlink:href="&url.base;/de/index.html">FreeBSD-Homepage</link> - aufzurufen.</para> - - - </example> - </sect3> - </sect2> - </sect1> -</chapter> |