<!-- 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: de-docproj/books/fdp-primer/sgml-markup/chapter.sgml,v 1.7 2005/02/26 12:20:55 mheinen Exp $

     basiert auf: 1.51
-->

<chapter id="sgml-markup">
  <title>SGML-Dokumente erstellen</title>

  <para>In diesem Kapitel werden die beiden vom FDP eingesetzen
    Auszeichnungssprachen HTML und DocBook behandelt. Hierbei
    beschr&auml;nkt sich dieses Kapitel auf die Elemente, die bei der
    t&auml;glichen Arbeit am ehesten zum Einsatz kommen werden.</para>
  
  <para>Beide Sprachen besitzen eine gro&szlig;e Anzahl von Elementen.
    Das erschwert es, das richtige Element in der richtigen Situation
    auszuw&auml;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&ouml;glichst viele
    Elemente beider Sprachen zu behandeln &ndash; dies w&auml;re nur
    eine Wiederholung der eigentlichen Sprachreferenz. Sofern es
    Unklarheiten zur Verwendung einzelner Elemente und Auszeichnung
    von bestimmten Sachverhalten gibt, k&ouml;nnen diese an &a.doc;
    geschickt werden.</para>
  
  <note>
    <title>Flu&szlig;- kontra Blockelemente</title>
    
    <!--@todo 
    Fussnote bzgl. der UEbersetzung von "inline" einfuegen.
    Oliver Fischer
    -->
    
    <para>Wenn im folgenden von
      <emphasis>Flu&szlig;elementen</emphasis> die Rede ist, sind
      damit Elemente gemeint, die in einem Blockelement auftreten
      k&ouml;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&szlig;text</quote>
          mit <quote>Flu&szlig;element</quote>
          &uuml;bersetzt.</para></footnote>.</para>
  </note>
  
  <sect1 id="sgml-markup-html">
    <title>HTML</title>
    
    <para>HTML<footnote><para>HyperText Markup Language</para>
      </footnote> ist die Auszeichnungssprache des
      WWWs<footnote><simpara>Wer mehr Informationen zu HTML
          w&uuml;nscht, kann diese beim <ulink
            url="http://www.w3.org/">W3C</ulink> finden.</simpara>
      </footnote>. Sie kommt bei der Erstellung der Webseiten des
      FreeBSD-Projektes zum Einsatz. F&uuml;r technische Dokumentationen
      sollte HTML jedoch nicht eingesetzt werden, da DocBook eine
      gr&ouml;&szlig;ere und bessere Auswahl an Elementen bietet. Folglich sollte
      HTML nur dann eingesetzt werden, wenn an den FreeBSD-Webseiten
      arbeitet wird.</para> 
    
    <para>Die HTML-Spezifikation liegt bis jetzt in mehreren Versionen
      vor: 1, 2, 3.0, 3.2 und (die aktuelle) 4.0. Von letzterer
      existieren zwei Varianten: <quote>streng</quote> (HTML 4.0
      Strict) und <quote>locker</quote> (HTML 4.0
      Transitional).</para>
    
    <para>Die HTML-DTDs  sind &uuml;ber den Port <filename
        role="package">textproc/html</filename> verf&uuml;gbar und werden
      automatisch als Teil des Metaports <filename
        role="package">textproc/docproj</filename>
      mitinstalliert.</para>
    
    <sect2>
      <title>Formale &Ouml;ffentliche Bezeichner</title>
      
      <!--@todo  Optimierungskandidat. Oliver Fischer -->
      <para>Da es mehrere Version von HTML gibt, existieren auch
        mehrere F&Ouml;Ps,  zu denen  ein HTML-Dokument konform
        erkl&auml;rt werden kann. Die Mehrzahl der sich auf der
        FreeBSD-Webseite befindenen HTML-Seiten sind zu der lockeren
        Version von HTML 4.0 konform.</para>
      
      <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
    </sect2>

    <sect2>
      <title>Die Elemente <sgmltag>head</sgmltag> und
        <sgmltag>body</sgmltag></title>

      <para>Ein HTML-Dokument unterteilt sich normalerweise in zwei
        Bereiche: <quote>head</quote> und <quote>body</quote>. Der
        Kopf (<foreignphrase>head</foreignphrase>) enth&auml;lt  Metadaten
        wie den Dokumententitel und Angaben zum Autor. Der Rumpf
        (<foreignphrase>body</foreignphrase>) umfa&szlig;t den eigentlichen
        Dokumenteninhalt, der f&uuml;r den Leser bestimmt ist. In einem
        HTML-Dokument werden diese Bereiche &uuml;ber die Elemente
        <sgmltag>head</sgmltag> und <sgmltag>body</sgmltag>
        voneinander abgegrenzt. Beide sind Kinder des Wurzelelementes
        <sgmltag>html</sgmltag>.</para>
      
      <example>
	<title>Die Struktur eines HTML-Dokumentes</title>
        
	<programlisting>&lt;html>
  &lt;head>
    &lt;title><replaceable>Der Dokumententitel</replaceable>&lt;/title>
  &lt;/head>

  &lt;body>

    &hellip;

  &lt;/body>
&lt;/html></programlisting>
      </example>
    </sect2>
    
    <sect2>
      <title>Blockelemente</title>
      
      <sect3>
	<title>&Uuml;berschriften</title>
        
        <para>HTML kennt sechs verschiedene Elemente, mit denen
          &Uuml;berschriften ausgezeichnet werden k&ouml;nnen. Das  bekannteste
          Element ist <sgmltag>h1</sgmltag>, das sich am Anfang der
          &Uuml;berschriftenhierarchie befindet. <sgmltag>h1</sgmltag>
          folgen die &Uuml;berschriftenelemente <sgmltag>h2</sgmltag> bis
          <sgmltag>h6</sgmltag>. Der Inhalt von
          <sgmltag>h<replaceable>N</replaceable></sgmltag> stellt den
          Text der  &Uuml;berschrift dar.</para>
        
	<example>
	  <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>&hellip;</title>
          
	  <para>F&uuml;gen Sie in eine der existierenden &Uuml;bungsdateien folgendes ein:</para>

	  <programlisting><![ RCDATA [<h1>Erstes Kapitel</h1>

<!-- Hier steht die Einf&uuml;hrung -->

<h2>Das ist die &Uuml;berschrift des ersten Kapitels</h2>

<!-- Hier steht der Inhalt des ersten Kapitels -->

<h3>Das ist die &Uuml;berschrift des ersten Unterkapitels</h3>

<!-- Hier steht der Inhalt des ersten Unterkapitels -->

<h2>Das ist die &Uuml;berschrift des zweiten Kapitels</h2>

<!-- Hier steht der Inhalt des zweiten Kapitels -->]]></programlisting>	    
	</example>
        
        <para>Eine HTML-Seite sollte immer nur eine &Uuml;berschrift
          <sgmltag>h1</sgmltag> haben. Dieser &Uuml;berschrift k&ouml;nnen
          beliebig viele Kapitel mit einer &Uuml;berschrift
          <sgmltag>h2</sgmltag> folgen, die selbst wiederum eine
          beliebige Anzahl von Kapiteln mit einer &Uuml;berschrift
          <sgmltag>h3</sgmltag> enthalten k&ouml;nnen. Diese
          Verschachtelung setzt sich bis zu Kapiteln mit einer
          <sgmltag>h6</sgmltag>-&Uuml;berschrift fort. Es sollte vermieden
          werden, Elemente in der &Uuml;berschriftenhierarchie
          auszulassen.</para>
        
	<example>
	  <title>Falsche Verschachtelung von &Uuml;berschriften</title>
          
	  <para>F&uuml;gen Sie in eine der existierenden &Uuml;bungsdateien folgendes ein:</para>
          
	  <programlisting><![ RCDATA [<h1>Erstes Kapitel</h1>

<!-- Allgemeines zum Dokument -->

<h3>Unterkapitel</h3>

<!-- h3 folgt direkt auf h1. h2 wurde ausgelassen -->]]></programlisting>
	</example>
      </sect3>
      
      <sect3>
	<title>Abs&auml;tze</title>
        
	<para>Abs&auml;tze k&ouml;nnen in HTML mit Hilfe des Elementes
          <sgmltag>p</sgmltag> ausgezeichnet werden.</para>
        
	<example>
	  <title>Abs&auml;tze mit dem Element <sgmltag>p</sgmltag></title>
          
	  <para>F&uuml;gen Sie in eine der existierenden &Uuml;bungsdateien folgendes ein:</para>
          
	  <programlisting><![ RCDATA [<p>Das hier, das ist ein Absatz. Abs&auml;tze k&ouml;nnen
  andere Elemente enhalten.</p>]]></programlisting>
	</example>
      </sect3>
      
      <sect3>
	<title>Blockzitate</title>
        
	<para>Ein Blockzitat ist ein etwas umfangreicheres Zitat aus
          einem anderen Text, das nicht zum aktuellen Absatz
          geh&ouml;rt.</para>
        
	<example>
	  <title>Blockzitat</title>
          
          <para>F&uuml;gen Sie in eine der existierenden &Uuml;bungsdateien
            folgendes ein:</para>
          
	  <programlisting><![ RCDATA [<blockquote>
  <p>Artikel 1: Menschenw&uuml;rde; Grundrechtsbindung der
    staatlichen Gewalt</p>

  <ol>
    <li>
      <p>Die W&uuml;rde des Menschen ist unantastbar. Sie zu achten
        und zu sch&uuml;tzen ist Verpflichtung aller staatlichen
        Gewalten.</p>
    </li>
    <li>
      <p>Das Deutsche Volk bekennt sich darum zu unverletzlichen
        und unver&auml;u&szlig;erlichen Menschenrechten als Grundlage jeder
        menschlichen Gemeinschaft, des Friedens und der
        Gerechtigkeit in der Welt.</p>
    </li>
    <li>
      <p>Die nachfolgenden Grundrechte binden Gesetzgebung,
        vollziehende Gewalt und Rechtsprechung als
        unmittelbar geltendes Recht.</p>
    </li>
  </ol>
</blockquote>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Listen</title>
        
        <para>HTML kennt drei Arten von Listen: sortierte, unsortierte
          und Definitionslisten. Ein Eintrag in einer sortierten Liste
          wird &uuml;blicherweise mit einer Nummer versehen, Eintr&auml;ge in
          unsortierten Listen hingegen mit einem Aufz&auml;hlungspunkt.
          Definitionslisten wiederum bestehen aus zwei Teilen: Der
          erste enth&auml;lt den Begriff der definiert werden soll und der
          zweite dessen Erl&auml;uterung.</para>

        <para>Sortierte Listen werden mit dem Element
          <sgmltag>ol</sgmltag> (f&uuml;r
          <foreignphrase><emphasis>o</emphasis>rdered
            <emphasis>l</emphasis>ist</foreignphrase>) ausgezeichnet,
          unsortierte Listen mit <sgmltag>ul</sgmltag> (f&uuml;r
          <foreignphrase><emphasis>u</emphasis>nordered
            <emphasis>l</emphasis>ist</foreignphrase>) und
          Definitionslisten mit <sgmltag>dl</sgmltag>.</para>
          

        <para>Listenpunkte sortierter und unsortierter Listen werden
          mit dem Element <sgmltag>li</sgmltag>  ausgezeichnet,
          welches Text oder andere Blockelemente enthalten kann.
          Begriffe, die in einer Definitionslisten enthalten sind,
          werden mit dem Element <sgmltag>dt</sgmltag> (f&uuml;r
          <foreignphrase><emphasis>d</emphasis>efinition
            <emphasis>t</emphasis>erm</foreignphrase>) ausgezeichnet.
          Die Erkl&auml;rung zu diesem Begriff wird mit Hilfe des Elementes
          <sgmltag>dd</sgmltag> (f&uuml;r <foreignphrase>definition
            description</foreignphrase>) markiert. So wie
          <sgmltag>li</sgmltag>, kann das Element
          <sgmltag>dd</sgmltag> ebenfalls andere Blockelemente
          aufnehmen.</para>
        
	<example>
	  <title>Listen mit <sgmltag>ul</sgmltag> und
            <sgmltag>ol</sgmltag> erstellen</title>

	  <para>F&uuml;gen Sie in eine der existierenden &Uuml;bungsdateien
            folgendes ein:</para>

	  <programlisting><![ RCDATA [<p>Jetzt folgt eine unsortierte Liste. Wahrscheinlich werden
  die einzelnen Eintr&auml;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&auml;ge bestehen aus mehreren Abs&auml;tzen.
  Jeder Listeneintrag ist nummeriert.</p>

<ol>
  <li><p>Das ist der erste Eintrag mit nur einem Absatz.</p></li>

  <li><p>Das ist der erste Absatz des zweiten Eintrags.</p>

    <p>Und das ist der zweite Absatz des zweiten Eintrags.</p></li>

  <li><p>Der dritte Eintrag besteht ebenfalls nur aus einem Eintrag.</p></li>
</ol>]]></programlisting>
	</example>

	<example>
	  <title>Definitionslisten mit <sgmltag>dl</sgmltag> erstellen</title>

          <para>F&uuml;gen Sie in eine der existierenden &Uuml;bungsdateien folgendes ein:</para>

	  <programlisting><![ RCDATA [<dl>
  <dt>Erster Begriff</dt>

  <dd><p>Erster Absatz der Erkl&auml;rung</p></dd>

    <p>Zweiter Absatz der Erkl&auml;rung.</p></dd>

  <dt>Zweiter Begriff</dt>

  <dd><p>Erster Absatz der Erkl&auml;rung.</p></dd>

  <dt>Dritter Begriff</dt>

  <dd>Erster Absatz der Erkl&auml;rung zum dritten Begriff.
    Beachtenswert ist, da&szlig; &lt;p&gt; nicht notwendig ist.</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&auml;llen ist es gewollt, da&szlig; die Formatierung
          eines Textes im Quelldokument erhalten bleibt, so da&szlig; der
          Leser diesen genau so sieht, wie ihn der Autor erstellt hat.
          In der HTML-Spezifikation ist daf&uuml;r das Element
          <sgmltag>pre</sgmltag> vorgesehen, welches daf&uuml;r sorgt, da&szlig;
          Zeilenumbr&uuml;che erhalten bleiben und Leerzeichen nicht
          zusammengefa&szlig;t werden. Browser verwenden f&uuml;r den
	  Inhalt des Elementes <sgmltag>pre</sgmltag>
	  &uuml;blicherweise eine Fixschrift.</para>

	<example>
	  <title>Vorformatierten Text mit <sgmltag>pre</sgmltag> erstellen</title>

          <para>Der Originaltext einer E-Mail l&auml;&szlig;t sich beispielsweise
            wie folgt einbinden:</para>
          
	  <!--<para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail
	    message;</para>-->

	  <programlisting><![ RCDATA [<pre>  From: nik@FreeBSD.org
  To: freebsd-doc@FreeBSD.org
  Subject: Neue Version verf&uuml;gbar

  Es ist eine neue Version der Fibel f&uuml;r neue Mitarbeiter am
  FreeBSD-Dokumentationsprojekt verf&uuml;gbar:

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

  Kommentare und Anmerkungen sind willkommen.

  N</pre>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Tabellen</title>

	<note>
          <para>Die meisten Textbrowser, beispielsweise Lynx, k&ouml;nnen
            Tabellen nicht besonders gut darstellen. Deshalb sollten
            Auszeichnungsalternativen in Betracht gezogen werden, um
            eine angemessene Darstellung sicherzustellen.</para>
	</note>

        <para>Tabellen lassen sich in HTML mit Hilfe des Elements
          <sgmltag>table</sgmltag> auszeichnen. Eine Tabelle setzt
          sich aus einer oder mehreren Zeilen (<sgmltag>tr</sgmltag>)
          zusammen, von denen jede mindestens eine Zelle
          (<sgmltag>td</sgmltag>) enth&auml;lt. Zellen k&ouml;nnen wiederum
          andere Blockelemente, wie Abs&auml;tze oder Listen, enthalten.
          Auch k&ouml;nnen sie auch andere Tabellen aufnehmen, wobei die
          Verschachtelungstiefe unbegrenzt ist. Soll die Tabellenzelle
          nur einen Textabsatz enthalten, ist es nicht notwendig den
          Text mit einem <sgmltag>p</sgmltag> zu umschlie&szlig;en.</para>
          
	<example>
	  <title>Einfache Tabelle mit <sgmltag>table</sgmltag></title>

	  <para>F&uuml;gen Sie in eine der existierenden &Uuml;bungsdateien folgendes ein:</para>

	  <programlisting><![ RCDATA [<p>Eine einfache 2x2 Tabelle.</p>

<table>
  <tr>
    <td>Obere linke Zelle</td>

    <td>Obere rechte Zelle</td>
  </tr>

  <tr>
    <td>Untere linke Zelle</td>

    <td>Untere rechte Zelle</td>
  </tr>
</table>]]></programlisting></example>
       
        <para>HTML kennt die M&ouml;glichkeit, da&szlig; sich eine
          Zelle mehrere Zeilen und/oder Spalten erstrecken kann.
          Sollen beispielsweise mehrere Spalten zusammenfassen werden,
          kann dies mit mit Hilfe des Attributes
          <literal>colspan</literal> erreicht werden, indem man ihm
          die Anzahl der zusammenzufassenden Spalten zuweist.
          &Auml;hnliches gilt f&uuml;r die Zusammenfassung von Zeilen:
          Hierf&uuml;r wird dem Attribut <literal>rowspan</literal>
          die Anzahl der zusammenzufassenden Zeilen zugewiesen.</para>
          
	<example>
	  <title>Anwendung des Attributes <literal>rowspan</literal></title>

	  <programlisting><![ RCDATA [<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&uuml;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><![ RCDATA [<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><![ RCDATA [<p>Eine Tablle mit 3-mal-3 Zellen. Oben links
  werden 2 mal 2 Zelle zusammengezogen.</p>

<table>
  <tr>
    <td colspan="2" rowspan="2">Gro&szlig;e obere linke Zelle</td>

    <td>Obere rechte Zelle</td>
  </tr>

  <tr>
    <!-- Da sich die zusammengefa&szlig;te Zelle &uuml;ber zwei Zeilen
         erstreckt, befindet sich das die durch dieses <td>
         definierte Zelle ganz rechts. -->            
	    
    <td>Mittlere rechte Zelle</td>
  </tr>

  <tr>
    <td>Untere linke Zelle</td>

    <td>Untere mittlere Zelle</td>

    <td>Untere rechte Zelle</td>
  </tr>
</table>]]></programlisting>
	</example>
      </sect3>
    </sect2>

    <sect2>
      <title>Flu&szlig;elemente</title>
      
      <sect3>
	<title>Hervorheben von Information</title>

        <para>Sollen sich bestimmte Informationen von anderen optisch
          abheben, kann dies mit den HTML-Tags
          <sgmltag>strong</sgmltag> und <sgmltag>em</sgmltag> erreicht
          werden. <sgmltag>strong</sgmltag> stellt dabei eine
          st&auml;rkere Hervorhebung  als <sgmltag>em</sgmltag> dar,
          wobei mit <sgmltag>strong</sgmltag> ausgezeichnete Elemente
          fett und mit <sgmltag>em</sgmltag> ausgezeichnete Elemente
          kursiv dargestellt werden. Allerdings ist diese Aussage
          nicht verl&auml;&szlig;lich, da die Darstellung vom Browser
          abh&auml;ngig ist.</para>
        
	<example>
	  <title>Text mit <sgmltag>em</sgmltag> und <sgmltag>strong</sgmltag>
            hervorheben</title>

	  <programlisting><![ RCDATA [<p><em>Dieses</em> Wort ist hervorgehoben,
  w&auml;hrend <strong>dieses noch st&auml;rker hervorgehoben ist.</p>]]></programlisting>
        </example>
      </sect3>
      
      <sect3>
        <!--? Was ist typografisch richtig: schr&auml;g oder kursiv?
              Oliver Fischer -->
        <title>Fett- und Schr&auml;gschrift</title>
        
        <para>Da mittels HTML auch Festlegungen &uuml;ber die
          Darstellung getroffen werden k&ouml;nnen, gibt es die
          M&ouml;glichkeit direkt zu bestimmen, da&szlig; bestimmte
          Inhalte fett oder kursiv dargestellt werden sollen. Mit
          <sgmltag>b</sgmltag> eingefa&szlig;te Inhalte werden fett
          und mit <sgmltag>i</sgmltag> eingefa&szlig;te kursiv
          dargestellt.</para>
        
	<example>
	  <title>Text mit <sgmltag>b</sgmltag> und <sgmltag>i</sgmltag>
            formatieren</title>

	  <programlisting><![ RCDATA [<p><b>Dieses</b> Wort wird fett dargestellt,
w&auml;hrend <i>dieses</i> kursiv dargestellt wird.</p>]]></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Nicht-proportionale Schrift f&uuml;r Texte</title>

        <para>Der Tag <sgmltag>tt</sgmltag> erlaubt es,
          Text in einer schreibmaschinen&auml;hnlichen
          Schrift darzustellen.</para>
        
	<example>
	  <title>Nicht-proportionale Schrift mit
            <sgmltag>tt</sgmltag></title>

	  <programlisting><![ RCDATA [<p>Dieses Dokument wurde urspr&uuml;nglich von 
  Nik Clayton geschrieben. Nick Clayton kann unter der E-Mail-Adresse
  <tt>nik@FreeBSD.org</tt> erreicht werden.</p>]]></programlisting>

	</example>
      </sect3>

      <sect3>
	<title>&Auml;nderung der Schriftgr&ouml;&szlig;e</title>
        
        <para>HTML bietet auch M&ouml;glichkeiten, um Einflu&szlig;
          auf die Schriftgr&ouml;&szlig;e zu nehmen, das hei&szlig;t,
          zu bestimmen, ob die Schrift gr&ouml;&szlig;er oder kleiner
          als die Standardschrift dargestellt werden soll. Es gibt
          drei verschiedene Wege, dies zu erreichen:</para>
        
	<orderedlist>
	  <listitem>
            <para>Mittels der Tags <sgmltag>big</sgmltag> und
              <sgmltag>small</sgmltag> kann die
              Darstellungsgr&ouml;&szlig;e des eingeschlossenen Textes
              vergr&ouml;&szlig;ert respektive verkleinert werden.
              HTML erlaubt es zudem, diese Tags zu verschachteln, so
              da&szlig; auch <literal>&lt;big&gt;&lt;big&gt;Das ist
                wesentlich
                gr&ouml;&szlig;er.&lt;/big&gt;&lt;/big&gt;</literal>
              geschrieben werden kann.</para>
	  </listitem>

	  <listitem>
            <para>Das gleiche Ergebnis kann &uuml;ber die Zuweisung der
              Werte <literal>1</literal> und <literal>-1</literal> an
              das Attribut <sgmltag role="attribute">size</sgmltag>
              des Tags <sgmltag>font</sgmltag> erreicht werden. Diese
              Vorgehensweise sollte allerdings als veraltet betrachtet
              werden, da der Einsatz eines CSS hierf&uuml;r die bessere
              L&ouml;sung darstellt.</para>
	  </listitem>

	  <listitem>
            <para>&Uuml;ber die Zuweisung von absoluten Werten im Bereich
              von <literal>1</literal> bis <literal>7</literal> an das
              Attribut <literal>size</literal> des Tags
              <sgmltag>font</sgmltag> <footnote>
                <para>Der Standardwert f&uuml;r <literal>size</literal> ist
                  <literal>3</literal>.</footnote>. Diese
              Herangehensweise ist ebenfalls veraltet und sollte nicht
              mehr angewandt werden.</para>
	  </listitem>
	</orderedlist>

	<example>
	  <title>Schriftgr&ouml;&szlig;e &auml;ndern mit
            <sgmltag>big</sgmltag>, <sgmltag>small</sgmltag> und
            <sgmltag>font</sgmltag></title>
          
	  <para>Die folgenden HTML-Schnipsel bewirken alle das gleiche:</para>

	  <programlisting><![ RCDATA [<p>Dieser Text ist <small>etwas kleiner</small>. Dieser
  jedoch <big>ein wenig gr&ouml;&szlig;er</big>.</p>

<p>Dieser Text ist <font size="-1">etwas kleiner</font>. Dieser
  jedoch <font size="+1">ein wenig gr&ouml;&szlig;er</font>.</p>

<p>Dieser Text ist <font size="2">etwas kleiner</font>. Dieser
  jedoch <font size="4">ein wenig gr&ouml;&szlig;er</font>.</p>]]></programlisting>
	</example>
      </sect3>
    </sect2>

    <sect2 id="links">
      <title>Links</title>

      <note>
	<para>Bei Links handelt es sich ebenfalls Flu&szlig;elemente.</para>
      </note>

      <sect3>
	<title>Auf andere Dokumente im WWW verweisen</title>

	<para>Um auf ein anderes Dokument im WWW zu verweisen,
	  m&uuml;ssen Sie die URL dieses Dokuments kennen.</para>

        <para>Links auf andere Dokumente im WWW werden in HTML durch
          den Tag <sgmltag>a</sgmltag> und dessen Attribute <sgmltag
            role="attribute">href</sgmltag>, das die Zieladresse
          enth&auml;lt, angelegt. Der Inhalt des Elementes wird selbst
          zum Link und seine Darstellung erfolgt verschieden vom
          &uuml;brigen Text. Meist geschieht das durch eine andere
          Schriftfarbe oder dadurch, da&szlig; der Linktext
          unterstrichen wird.</para>
        
	<example>
	  <title><literal>&lt;a href="..."&gt;</literal> benutzen</title>

	  <programlisting><![ RCDATA [<p>Weitere Informationen stehen auf der
  <a href="http://www.FreeBSD.org/">FreeBSD-Webseite</a> zur Verf&uuml;gung.</p>]]></programlisting>
	</example>
        
        <para>Beim Aufruf dieses Links wird das referenzierte Dokument vom
          Browser geladen und mit dessen Seitenanfang dargestellt.</para>
      </sect3>
      
      <sect3>
	<title>Auf bestimmte Dokumentenabschnitte verweisen</title>

        <para>HTML unterst&uuml;tzt neben einfachen Links auch solche, die
          auf einen bestimmten Abschnitt innerhalb eines Dokumentes
          verweisen. Dazu m&uuml;ssen die Abschnitte, auf die verwiesen
          werden soll, mit Hilfe von sogenannten <quote>Ankern</quote>
          markiert werden. Diese Anker k&ouml;nnen ebenfalls mit Hilfe des
          Tags <sgmltag>a</sgmltag> gesetzt werden, nur das anstelle
          von <sgmltag role="attribute">href</sgmltag> das Attribut
          <sgmltag role="attribute">name</sgmltag> gesetzt werden
          mu&szlig;.</para>
          
	<example>
	  <title>Anwendung von <literal>&lt;a name="..."&gt;</literal></title>

	  <programlisting><![ RCDATA [<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,
          mu&szlig; 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&uuml;r dieses Beispiel wird davon ausgegangen, da&szlig; der mit
            <literal>absatz1</literal> gekennzeichnete Absatz sich in
            der HTML-Datei <filename>foo.html</filename>
            befindet.</para>
          
	  <programlisting><![ RCDATA [<p>Weitere Informationen k&ouml;nnen im
  <a href="foo.html#absatz1">ersten Absatz</a> der Datei
  <tt>foo.html</tt> gefunden werden.</p>]]></programlisting>
	</example>

      </sect3>
    </sect2>
  </sect1>
  
  <sect1 id="sgml-markup-docbook">
    <title>Die DocBook DTD</title>

    <para>DocBook wurde von der <ulink
        url="http://www.oreilly.com/davenport/">Davenport
        Group</ulink> mit dem Ziel einer DTD zur Erstellung
      technischer Dokumentationen entwickelt. Daher ist DocBook sehr
      stark auf die Beschreibung von Inhalten, als auf deren
      Darstellung ausgerichtet. Damit steht sie im Gegensatz zu
      LinuxDoc und HTML.</para>
    
    <note>
      <title>Formelle und informelle Elemente</title>

      <para>Einige Elemente der DocBook DTD sind in zwei Varianten
        vorhanden: <emphasis>formell</emphasis> und
        <emphasis>informell</emphasis>. &Uuml;blicherweise besitzt die
        formelle Variante einen Titel, dem der eigentliche
        Elementeninhalt folgt. Die informelle Variante hingegen hat
        keinen Titel.</para>
    </note>
    
    <para>Die DocBook DTD ist in der Portssammlung im Port <filename
        role="package">textproc/docbook</filename> enthalten und wird
      bei der Installation von <filename
        role="package">textproc/docproj</filename> automatisch
      mitinstalliert.</para>
    
    <sect2>
      <title>Die FreeBSD-Erweiterungen</title>

      <para>F&uuml;r das FDP wurde die DocBook DTD durch das
        FreeBSD-Dokumentationsproject um zus&auml;tzliche Elemente
        erweitert, um damit pr&auml;zisiere
        Auszeichnungsm&ouml;glichkeiten zur Verf&uuml;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&uuml;r die Arbeit des FDPs als n&uuml;tzlich erschienen.
          F&uuml;r den Fall, das in den anderen *nix-Lagern (NetBSD,
          OpenBSD, Linux,&hellip;) Interesse daran besteht, gemeinsam
          eine Standarderweiterung f&uuml;r die DocBook DTD zu
          entwickeln, kann mit &a.nik; Verbindung aufgenommen
          werden.</para>
      </note>

      <para>Zum jetzigen Zeitpunkt sind die FreeBSD-Erweiterungen
        nicht Bestandteil der Portssammlung. Sie werden im
        FreeBSD-CVS-Archiv (<ulink
          url="http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">doc/share/sgml/freebsd.dtd</ulink>) 
        verwaltet.</para>
    </sect2>
    
    <sect2>
      <title>Formelle &Ouml;ffentliche Bezeichner</title>

      <para>In &Uuml;bereinstimmung mir der DocBook-Richtlinie zur
        Erstellung von Bezeichnern f&uuml;r DocBook-Erweiterungen lautet
        der Bezeichner der erweiterten FreeBSD-Variante:</para>
      
      <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
    </sect2>

    <sect2 id="docbookstructure">
      <title>Die Struktur von DocBook-Dokumenten</title>

      <para>DocBook erlaubt es, Dokumente auf verschiedene Weise zu
        strukturieren. Innerhalb des FDPs werden haupts&auml;chlich zwei
        Arten von DocBook-Dokumenten verwendet: Buch und Artikel.
        Beide unterscheiden sich darin, da&szlig; ein Buch auf der obersten
        Ebene durch <sgmltag>chapter</sgmltag>-Elemente strukturiert
        wird. Sollte das noch nicht ausreichend sein, k&ouml;nnen die
        einzelnen Kapitel eines Buches mit Hilfe des Elementes
        <sgmltag>part</sgmltag> in Teile aufgespalten werden. Das
        Handbuch zum Beispiel ist auf diese Weise aufgebaut.</para>

      <para>Kapitel (<sgmltag>chapter</sgmltag>) k&ouml;nnen weiterhin in
        Unterkapitel unterteilt werden. Diese werden durch die
        Elemente <sgmltag>sect1</sgmltag>  ausgezeichnet. Soll ein
        Unterkapitel selbst weitere Unterkapitel enthalten, kann das
        &uuml;ber das Element <sgmltag>sect2</sgmltag> geschehen. Diese
        Unterteilung kann bis zur Tiefe von f&uuml;nf Unterkapiteln &ndash;
        &uuml;ber die Elemente <sgmltag>sect3</sgmltag>,
        <sgmltag>sect4</sgmltag> und <sgmltag>sect5</sgmltag> &ndash;
        fortgef&uuml;hrt werden. Der eigentliche Inhalt, um den es ja in
        dem Artikel oder Buch geht, wird unterhalb der hier genannten
        Elemente eingef&uuml;gt.</para>
      
      <para>Vom Aufbau her ist ein Artikel ist einfacher strukturiert
        als ein Buch. So kann ein Artikel beispielsweise keine Kapitel
        (<sgmltag>chapter</sgmltag>) enthalten. Stattdessen kann der
        Inhalt eines Artikels nur durch die schon bekannten
        <sgmltag>sect<replaceable>N</replaceable></sgmltag>-Elemente
        in einen oder mehrere Abschnitte gegliedert werden.
	&Uuml;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&uuml;r Texte, die nicht in mehrere Kapitel
        aufgeteilt werden m&uuml;ssen und mit einem Umfang von
        ungef&auml;hr 20 bis 25&nbsp;Seiten vergleichsweise kurz sind.
        Nat&uuml;rlich ist das nur eine Richtlinie. B&uuml;cher sind
        dementsprechend am besten f&uuml;r lange Texte geeignet, die
        sich sinnvoll in Kapitel unterteilen lassen und
        m&ouml;glichweiser noch Anh&auml;nge und &auml;hnliches
        enthalten k&ouml;nnen.</para>

      <para>Alle <ulink url="../../../../docs.html">Tutorien von
          FreeBSD</ulink> sind als Artikel verfa&szlig;t, w&auml;hrend
        hingegen die <ulink
          url="../faq/index.html">FreeBSD-FAQ</ulink> und das <ulink
          url="../handbook/index.html">FreeBSD-Handbuch</ulink> als
        B&uuml;cher verfa&szlig;t wurden.</para>
      
      <sect3>
	<title>B&uuml;cher schreiben</title>

        <para>Der Inhalt eines Buches wird in einem
          <sgmltag>book</sgmltag>-Element abgelegt.  Neben dem
	  Textteil des Buches kann dieses Element weitergehende
	  Informationen &uuml;ber das Buch selbst,
	  wie Meta-Informationen zum Erstellen eines
	  Stichwortverzeichnisses oder zus&auml;tzliche
	  Inhalte zum Erstellen einer Titelei, enthalten.  Diese
	  zus&auml;tzlichen Inhalte sollten in einem
          <sgmltag>bookinfo</sgmltag>-Element abgelegt werden.</para>
 
	<example>
	  <title>Buchvorlage <sgmltag>book</sgmltag> mit
            <sgmltag>bookinfo</sgmltag></title>

	  <!-- Can't put this in a marked section because of the
               replaceable elements -->
	  <programlisting>&lt;book>
  &lt;bookinfo>
    &lt;title><replaceable>Titel</replaceable>&lt;/title>
    &lt;author>
      &lt;firstname><replaceable>Vorname</replaceable>&lt;/firstname>
      &lt;surname><replaceable>Nachname</replaceable>&lt;/surname>
      &lt;affiliation>
        &lt;address>&lt;email><replaceable>Emailadresse</replaceable>&lt;/email>&lt;/address>
      &lt;/affiliation>
    &lt;/author>

    &lt;copyright>
      &lt;year><replaceable>1998</replaceable>&lt;/year>
      &lt;holder role="mailto:<replaceable>Emailadresse</replaceable>"><replaceable>Vollst&auml;ndiger Name</replaceable>&lt;/holder>
    &lt;/copyright>

    &lt;releaseinfo>&#36;FreeBSD&#36;&lt;/releaseinfo>
            
    &lt;abstract>
      &lt;para><replaceable>Kurze Zusammenfassung des Buchinhaltes.</replaceable>&lt;/para>
    &lt;/abstract>
  &lt;/bookinfo>

  &hellip;

&lt;/book></programlisting>
	</example>
      </sect3>

      <sect3>
	<title>Artikel schreiben</title>

        <para>Der Inhalt eines Artikels wird in einem
          <sgmltag>article</sgmltag>-Element abgelegt.  Neben
	  dem Textteil kann dieses Element weitere Teile,
	  wie Meta-Informationen zum Erstellen eines
	  Stichwortverzeichnisses oder zus&auml;tzliche
	  Inhalte zum Erstellen einer Titelei, enthalten.
          Analog zu einem Buch, sollten diese Informationen in einem
          <sgmltag>articleinfo</sgmltag>-Element abgelegt
          werden.</para>

	<example>
	  <title>Artikelvorlage <sgmltag>article</sgmltag> mit
            <sgmltag>articleinfo</sgmltag></title>

	  <!-- Can't put this in a marked section because of the
               replaceable elements -->
	  <programlisting>&lt;article>
  &lt;articleinfo>
    &lt;title><replaceable>Titel</replaceable>&lt;/title>
    
    &lt;author>
      &lt;firstname><replaceable>Vorname</replaceable>&lt;/firstname>
      &lt;surname><replaceable>Nachname</replaceable>&lt;/surname>
      &lt;affiliation>
        &lt;address>&lt;email><replaceable>Emailadresse</replaceable>&lt;/email>&lt;/address>
      &lt;/affiliation>
    &lt;/author>

    &lt;copyright>
      &lt;year><replaceable>1998</replaceable>&lt;/year>
      &lt;holder role="mailto:<replaceable>Emailadresse</replaceable>"><replaceable>Vollst&auml;ndiger Name</replaceable>&lt;/holder>
    &lt;/copyright>

    &lt;releaseinfo>&#36;FreeBSD&#36;&lt;/releaseinfo>

    &lt;abstract>
      &lt;para><replaceable>Kurze Zusammenfassung des Artikelinhalts.</replaceable>&lt;/para>
    &lt;/abstract>
  &lt;/articleinfo>

  &hellip;

&lt;/article></programlisting>
	</example>	
      </sect3>
      
      <sect3>
        <title>Kapitel</title>

        <para>Kapitel werden mit dem
          <sgmltag>chapter</sgmltag>-Element angelegt und m&uuml;ssen ein
          <sgmltag>title</sgmltag>-Element enthalten. Verwendet werden
          k&ouml;nnen sie nur in B&uuml;chern.</para>
        
	<example>
	  <title>Ein einfaches Kapitel</title>

	  <programlisting><![ RCDATA [<chapter>
  <title>Kapitel&uuml;berschrift</title>

  &hellip;
</chapter>]]></programlisting>
	</example>

        <para>Kapitel k&ouml;nnen nicht leer sein. Nebem einem
          <sgmltag>title</sgmltag>-Element m&uuml;ssen sie weiteren Inhalt
          beinhalten. Falls ein leeres Kapitel ben&ouml;tig wird, kann dies
          durch das Einf&uuml;gen eines leeren Absatzes
          (<sgmltag>para</sgmltag>) erreicht werden.</para>
      
	<example>
	  <title>Ein leeres Kapitel</title>

	  <programlisting><![ CDATA [<chapter>
  <title>Das ist ein leeres Kapitel</title>

  <para></para>
</chapter>]]></programlisting>	    
	</example>
      </sect3>

      <sect3 id="unterkapitel">
	<title>Unterkapitel</title>

        <!-- Bei der Uebersetzung dieser Stelle bin ich
             bewusst vom Original abgewichen, da ich die
             Begriffe Kapitel und Kapitel anstatt
             Kapitel und Abschnitt benutze. Eine
             originalgetreue Uebersetzung wuerde somit an dieser
             Stelle nur zu Verwirrung fuehren.
             Oliver Fischer, 14.04.2004 -->
        
        <para>B&uuml;cher werden auf der obersten Gliederungsebene
          durch <sgmltag>chapter</sgmltag>-Elemente in Kapitel
          unterteilt. Eine weitergehende Untergliederung kann durch
          das Anlegen von Unterkapiteln erreicht werden. Im Gegensatz
          zu Kapiteln, die durch <sgmltag>chapter</sgmltag>-Elemente
          ausgezeichnet werden, erfolgt die Auszeichnung von
          Unterkapitel mit dem Element
          <sgmltag>sect<replaceable>n</replaceable></sgmltag>. Das
          <replaceable>n</replaceable> in Elementnamen trifft eine
          Aussage &uuml;ber die Gliederungstiefe, auf der sich das
          Unterkapitel befindet. Ein  <sgmltag>sect1</sgmltag>-Element
          kann mehrere Elemente vom Typ <sgmltag>sect2</sgmltag>
          enthalten, die die Unterkapitel der
          n&auml;chsten Gliederungsebene darstellen.
          <sgmltag>sect5</sgmltag> ist das letzte Element, das auf
          diese Art zur Gliederung eingesetzt werden kann.</para>

	<example>
	  <title>Unterkapitel</title>

	  <programlisting><![ RCDATA [<chapter>
  <title>Ein Beispielkapitel</title>

  <para>Ein beliebiger Text.</para>

  <sect1>
    <title>Erster Abschnitt (1.1)</title>

    &hellip;
  </sect1>

  <sect1>
    <title>Zweiter Abschnitt (1.2)</title>

    <sect2>
      <title>Erster Unterabschnitt (1.2.1)</title>

      <sect3>
        <title>Erster Unterunterabschnitt (1.2.1.1)</title>

         &hellip;
      </sect3>
    </sect2>

    <sect2>
      <title>Zweiter Unterabschnitt (1.2.2)</title>

      &hellip;
    </sect2>
  </sect1>
</chapter>]]></programlisting>
	</example>
	
	<note>
          <para>Die Unterkapitel dieses Beispiels wurden zu
            Demonstrationszwecken manuell durchnummeriert. In
            <quote>normalen</quote> Dokumenten wird diese Aufgabe von
            den Stylesheets &uuml;bernommen.</para>
	</note>
      </sect3>
      
      <sect3>
	<title>B&uuml;cher mittels <sgmltag>part</sgmltag>
          unterteilen</title>

        <para>In den F&auml;llen, in denen die Unteilung eines Buches in
          Kapitel nicht ausreichend ist, k&ouml;nnen mehrere
	  Kapitel mit dem Element <sgmltag>part</sgmltag> zu
	  einem Teil zusammengefasst werden.</para>
          
	<programlisting><![ RCDATA [<part>
  <title>Einf&uuml;hrung</title>

  <chapter>
    <title>&Uuml;berblick</title>

     &hellip;
  </chapter>

  <chapter>
    <title>Was ist FreeBSD?</title>

    &hellip;
  </chapter>

  <chapter>
    <title>Die Geschichte von FreeBSD</title>

    &hellip;
  </chapter>
</part>]]></programlisting>
      </sect3>
    </sect2>
    
    <sect2>
      <title>Blockelemente</title>
      
      <sect3>
	<title>Abs&auml;tze</title>

	<para>DocBook kennt drei Arten von Abs&auml;tzen: Abs&auml;tze
          mit &Uuml;berschrift (<sgmltag>formalpara</sgmltag>),
          normale Abs&auml;tze (<sgmltag>para</sgmltag>) und einfache
          Abs&auml;tze (<sgmltag>simpara</sgmltag>).</para>

        <para>Normale Abs&auml;tze und einfache Abs&auml;tze
          unterscheiden sich dadurch, da&szlig; innerhalb von
          <sgmltag>para</sgmltag> Blockelemente erlaubt sind,
          innerhalb von <sgmltag>simpara</sgmltag> hingegen nicht. Es
          ist empfehlenswert, <sgmltag>para</sgmltag> den Vorzug
          zu geben.</para>

	<example>
	  <title>Absatz mit <sgmltag>para</sgmltag></title>

	  <programlisting><![ RCDATA [<para>Das ist ein Absatz. Abs&auml;tze k&ouml;nnen fast jedes andere
  Element aufnehmen.</para>]]></programlisting>

	  <para>Darstellung:</para>
	  
	 <para>Das ist ein Absatz. Abs&auml;tze k&ouml;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&ouml;nnen
          Blockzitate eine &Uuml;berschrift haben und die Zitatquelle
          nennen.</para>

	<example>
	  <title><sgmltag>blockquote</sgmltag></title>
          
	  <programlisting><![ CDATA [<para>Ein Auszug aus dem Grundgesetz:</para>
            
<blockquote>
  <title>Menschenw&uuml;rde; Grundrechtsbindung der staatlichen Gewalt</title>
            
  <attribution>Aus dem Grundgesetz</attribution>

  <orderedlist>
    <listitem>
      <para>Die W&uuml;rde des Menschen ist unantastbar. Sie zu achten
        und zu sch&uuml;tzen ist Verpflichtung aller staatlichen
        Gewalten.</para>
    </listitem>
    <listitem>
      <para>Das Deutsche Volk bekennt sich darum zu unverletzlichen
        und unver&auml;u&szlig;erlichen Menschenrechten als Grundlage jeder
        menschlichen Gemeinschaft, des Friedens und der
        Gerechtigkeit in der Welt.</para>
    </listitem>
    <listitem>
      <para>Die nachfolgenden Grundrechte binden Gesetzgebung,
        vollziehende Gewalt und Rechtsprechung als
        unmittelbar geltendes Recht.</para>
    </listitem>
  </orderedlist>
</blockquote>]]></programlisting>

	  <para>Darstellung:</para>

          <blockquote>
            <title>Menschenw&uuml;rde; Grundrechtsbindung der
              staatlichen Gewalt</title>
            
            <attribution>Aus dem Grundgesetz</attribution>
            
            <orderedlist>
              <listitem>
                <para>Die W&uuml;rde des Menschen ist unantastbar. Sie
                  zu achten und zu sch&uuml;tzen ist Verpflichtung
                  aller staatlichen Gewalten.</para>
              </listitem>
              <listitem>
                <para>Das Deutsche Volk bekennt sich darum zu
                  unverletzlichen und unver&auml;u&szlig;erlichen
                  Menschenrechten als Grundlage jeder menschlichen
                  Gemeinschaft, des Friedens und der Gerechtigkeit in
                  der Welt.</para>
              </listitem>
              <listitem>
                <para>Die nachfolgenden Grundrechte binden
                  Gesetzgebung, vollziehende Gewalt und Rechtsprechung
                  als unmittelbar geltendes Recht.</para>
              </listitem>
            </orderedlist>
          </blockquote>          
	</example>
      </sect3>
      
      <sect3>
	<title>Tipps, Anmerkungen, Warnungen, wichtige Informationen
          und Randbemerkungen</title>
        
        <para>In bestimmten F&auml;llen kann es n&uuml;tzlich sein,
          dem Leser zus&auml;tzliche Informationen zu geben, die sich
          vom Haupttext abheben, damit der Leser sie besser wahrnimmt.
          Abh&auml;ngig von der Art der Information, k&ouml;nnen
          solche Stellen mit einem der Elemente <sgmltag>tip</sgmltag>
          (f&uuml;r Tipps), <sgmltag>note</sgmltag> (f&uuml;r
          Anmerkungen), <sgmltag>warning</sgmltag> (f&uuml;r
          Warnungen), <sgmltag>caution</sgmltag> (f&uuml;r besonders
          ernstzunehmende Warnungen) und <sgmltag>important</sgmltag>
          (f&uuml;r wichtige Anmerkungen) ausgezeichnet werden. Trifft
          keines dieser Element f&uuml;r die auszuzeichnende Stelle
          zu, sollte diese mit dem Element <sgmltag>sidebar</sgmltag>
          ausgezeichnet werden.</para>

        <para>Da die richtige Einordnung einer auszuzeichnenden
          Textstelle nicht immer leicht zu treffen ist, werden in der
          DocBook-Dokumentation folgende Empfehlungen gegeben:</para>

	<itemizedlist>
	  <listitem>
            <para>Eine Anmerkung (<sgmltag>note</sgmltag>) ist eine
              Information, die von jedem Leser beachtet werden
              sollte.</para>
	  </listitem>
	  
	  <listitem>
            <para>Eine wichtige Anmerkung
              (<sgmltag>important</sgmltag>) eine Variation einer
              Anmerkung.</para>
	  </listitem>

	  <listitem>
            <para>Eine Warnung (<sgmltag>warning</sgmltag>)
              betrifft einen m&ouml;glichen Hardwareschaden
              oder weist auf eine Gefahr f&uuml;r Leib und Leben
              hin.</para>
          </listitem>
	  
	  <listitem>
	    <para>Eine besonders ernstzunehmende Warnung
              (<sgmltag>caution</sgmltag>) betrifft einen m&ouml;glichen
              Datenverlust oder Softwareschaden.</para>
	  </listitem>
        </itemizedlist>
        	
	<example>
	  <title><sgmltag>warning</sgmltag></title>

	  <programlisting><![ RCDATA [<warning>
  <para>Wenn Sie FreeBSD auf Ihrer Festplatte installieren,
    kann es sein, da&amp;szlig; Sie Windows nie mehr benutzen wollen.</para>
</warning>]]></programlisting>
        </example>
	  
	 <!-- Need to do this outside of the example -->
	<warning>
          <para>Wenn Sie FreeBSD auf Ihrer Festplatte installieren,
            kann es sein, da&szlig; 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&uuml;r den Benutzer
          &uuml;bersichtlich darzustellen oder eine Abfolge von
          Arbeitsschritten zu beschreiben, die notwendig sind, um ein
          bestimmtes Ziel zu erreichen. Zur Auszeichnung von Listen
          stellt DocBook die Elemente <sgmltag>itemizedlist</sgmltag>,
          <sgmltag>orderedlist</sgmltag> und
          <sgmltag>procedure</sgmltag> zur Verf&uuml;gung.<footnote>
            <para>DocBook kennt noch andere Elemente f&uuml;r die
              Auszeichnung von Listen, die an dieser Stelle jedoch
              nicht behandelt werden.</para>
          </footnote>.</para>

        <para><sgmltag>itemizedlist</sgmltag> und
          <sgmltag>orderedlist</sgmltag> &auml;hneln sehr stark ihren
          HTML-Gegenst&uuml;cken <sgmltag>ul</sgmltag> und
          <sgmltag>ol</sgmltag>. Beide Listenarten m&uuml;ssen
          mindestens ein Element <sgmltag>listitem</sgmltag>
          enthalten.  Das <sgmltag>listitem</sgmltag> Element
          mu&szlig; mindestens ein weiteres Blockelement
          enthalten.</para>

        <para><sgmltag>procedure</sgmltag> unterscheidet sich ein
          wenig von den vorhergehenden. Es enth&auml;lt
          <sgmltag>step</sgmltag>-Elemente, die wiederum
          <sgmltag>step</sgmltag>- oder
          <sgmltag>substel</sgmltag>-Elemente enthalten k&ouml;nnen.
          Ein <sgmltag>step</sgmltag>-Element kann nur Blockelemente
          aufnehmen.</para>

	<example>
	  <title><sgmltag>itemizedlist</sgmltag>,
            <sgmltag>orderedlist</sgmltag> und
            <sgmltag>procedure</sgmltag></title>

	  <programlisting><![ RCDATA [<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&auml;hlungselement.</para>
  </listitem>
            
  <listitem>
    <para>Das ist das zweite Aufz&auml;hlungselement.</para>
  </listitem>
</orderedlist>

<procedure>
  <step>
    <para>Machen Sie zuerst dies.</para>
  </step>

  <step>
    <para>Und dann machen Sie das..</para>
  </step>

  <step>
    <para>Und jetzt noch das&hellip;</para>
  </step>
</procedure>]]></programlisting>
	  
	  <para>Darstellung:</para>
          
          <itemizedlist>
            <listitem>
              <para>Das ist das erste Listenelement.</para>
            </listitem>
            
            <listitem>
              <para>Das ist das zweite Listenelement.</para>
            </listitem>
          </itemizedlist>
          
          <orderedlist>
            <listitem>
              <para>Das ist das erste Aufz&auml;hlungselement.</para>
            </listitem>
            
            <listitem>
              <para>Das ist das zweite Aufz&auml;hlungselement.</para>
            </listitem>
          </orderedlist>
        </example>
        
        <procedure>
          <step>
            <para>Machen Sie zuerst dies.</para>
          </step>
          
          <step>
            <para>Und dann machen Sie das..</para>
          </step>
          
          <step>
            <para>Und jetzt noch das&hellip;</para>
          </step>
        </procedure>          
      </sect3>
      
      <sect3>
	<title>Dateiinhalte auszeichnen</title>

        <para>Technische Dokumente enthalten oft auch
          Konfigurationsbeispiele oder Quellcodeschnipsel. Zur
          Auszeichnung dieser Inhalte, stellt Docbook das Element
          <sgmltag>programmlisting</sgmltag> zur Verf&uuml;gung. Im
          Gegensatz zu anderen DocBook-Elementen wird der
          Elementinhalt von <sgmltag>programmlisting</sgmltag>
          <emphasis>nicht</emphasis>  normalisiert, das hei&szlig;t,
          da&szlig; alle Leerzeichen, Tabulatoren und
          Zeilenumbr&uuml;che unver&auml;ndert &uuml;bernommen werden.
          Aus diesem Grund ist es unter anderem wichtig, da&szlig;
          sich der &ouml;ffende Tag in der selben Zeile wie der Anfang
          des darzustellenden Textes befindet. Gleiches gilt f&uuml;r
          den schlie&szlig;enden Tag: Er mu&szlig; sich am Ende der
          letzten Zeile befinden. Wird das nicht beachtet, kann es
          sein, da&szlig; unerwartete Leerzeichen und Leerzeilen in
          der Ausgabe auftauchen.</para>
        
	<example>
	  <title><sgmltag>programlisting</sgmltag></title>

	  <programlisting><![ RCDATA[<para>Am Ende sollte Ihr Programm wie folgt
  aussehen:</para>

<programlisting>#include &amp;lt;stdio.h&amp;gt;
            
int
main(void)
{
    printf("Hallo Welt!\n");
}</programlisting>]]></programlisting>

          <para>Die spitzen Klammern der
            <literal>#include</literal>-Anweisung k&ouml;nnen nicht direkt
            verwendet werden, sondern m&uuml;ssen &uuml;ber ihre Entit&auml;ten
            eingebunden werden.</para>

	  <para>Darstellung:</para>
	    
	  <para>Am Ende sollte Ihr Programm wie folgt aussehen:</para>
	    
	  <programlisting>#include &lt;stdio.h&gt;

int
main(void)
{
    printf("Hallo Welt!\n");
}</programlisting>	    
	</example>
      </sect3>

      <sect3>
	<title>Textanmerkungen</title>

        <para>Textanmerkungen<footnote><para>
              auf Englisch:
              <foreignphrase>callout</foreignphrase></para></footnote>
          sind ein Mechanismus, um auf bestimmte Stellen in einem
          vorhergehenden Beispiel oder Text zu verweisen.</para>
                
        <para>Um solche Verweise anzulegen, m&uuml;ssen die betreffenden
          Stellen in den Beispielen
          (<sgmltag>programlisting</sgmltag>,
          <sgmltag>literallayout</sgmltag>, &hellip;) mit
          <sgmltag>co</sgmltag>-Elementen markiert werden, wobei jedes
          Element ein eindeutiges <literal>id</literal>-Attribut
          besitzen mu&szlig;. Anschlie&szlig;end sollte ein
          <sgmltag>calloutlist</sgmltag>-Element eingef&uuml;gt werden,
          dessen Elemente sich auf die <sgmltag>co</sgmltag>-Elemente
          des Beispiels beziehen und die jeweiligen Anmerkungen
          enthalten.</para>

	<example>
	  <title>Das <sgmltag>co</sgmltag>- und das
            <sgmltag>calloutlist</sgmltag>-Element</title>

	  <programlisting><![ RCDATA[<para>Am Ende sollte Ihr Programm wie folgt
  aussehen:</para>

<programlisting>#include &amp;lt;stdio.h&amp;gt; <co id="co-ex-include">

int <co id="co-ex-return">
main(void)
{
    printf("Hallo Welt\n"); <co id="co-ex-printf">
}</programlisting>

<calloutlist>
  <callout arearefs="co-ex-include">
    <para>Bindet die Headerdatei <filename>stdio.h</filename> ein.</para>
  </callout>

  <callout arearefs="co-ex-return">
    <para>Bestimmt den Typ des R&uuml;ckgabewertes von <function>main()</function>.</para>
  </callout>

  <callout arearefs="co-ex-printf">
    <para>Ruft die Funktion <function>printf()</function> auf, die
      <literal>Hallo Welt!</literal> auf der Standardausgabe ausgibt</para>
  </callout>
</calloutlist>]]></programlisting>
            
            <para>Darstellung:</para>

          <para>Am Ende sollte Ihr Programm wie folgt aussehen:</para>

          <programlisting>#include &amp;lt;stdio.h&amp;gt; <co id="co-ex-include">

int <co id="co-ex-return">
main(void)
{
    printf("Hallo Welt\n"); <co id="co-ex-printf">
}</programlisting>

          <calloutlist>
            <callout arearefs="co-ex-include">
              <para>Bindet die Headerdatei <filename>stdio.h</filename> ein.</para>
            </callout>
            
            <callout arearefs="co-ex-return">
              <para>Bestimmt den Typ des R&uuml;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 &uuml;bernommen wird. Stattdessen sollten Tabellen
          nur f&uuml;r die Auszeichnung von Daten in Tabellenform genutzt
          werden.</para>

        <para>Vereinfacht betrachtet (f&uuml;r Details sollte die
          DocBook-Dokumentation zu Rate gezogen werden) besteht eine
          Tabelle, die entweder als formelle oder als informelle
          Tabelle angelegt werden kann, aus einem
          <sgmltag>table</sgmltag>-Element. Dieses Element selbst
          beinhaltet mindestens ein Element <sgmltag>tgroup</sgmltag>,
          das &uuml;ber ein Attribut die Spaltenanzahl der Tabelle
          bestimmt. Innerhalb des Elementes <sgmltag>tgroup</sgmltag>
          kann sich ein Element <sgmltag>thead</sgmltag> mit den
          Spalten&uuml;berschriften  und ein Element
          <sgmltag>tbody</sgmltag> mit dem eigentlichen Tabelleninhalt
          befinden. Beide Elemente beinhalten
          <sgmltag>row</sgmltag>-Elemente, die wiederum
          <sgmltag>entry</sgmltag>-Elemente beinhalten. Jedes
          <sgmltag>entry</sgmltag>-Element stellt eine einzelne
          Tabellenzelle dar.</para>

	<example>
	  <title>Tabellen mittels <sgmltag>informaltable</sgmltag>
            auszeichnen</title>

	  <programlisting><![ RCDATA [<informaltable>
  <tgroup cols="2">
    <thead>
      <row>
        <entry>Spalten&uuml;berschrift 1</entry>
        <entry>Spalten&uuml;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>
	    <tgroup cols="2">
	      <thead>
		<row>
		  <entry>Spalten&uuml;berschrift 1</entry>
		  <entry>Spalten&uuml;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>Soll die Tabelle keinen Rand haben, kann das Attribut
          <literal>frame</literal> mit dem Wert
          <literal>none</literal> dem Element
          <sgmltag>informaltable</sgmltag> hinzugef&uuml;gt werden
	  (<literal>&lt;informaltable frame="none"&gt;</literal>)).</para>
          
	<example>
	  <title>Tabelle mit Attribut
            <literal>frame="none"</literal></title>
	  
	  <para>Darstellung:</para>
	
	  <informaltable frame="none">
	    <tgroup cols="2">
	      <thead>
		<row>
		  <entry>Spalten&uuml;berschrift 1</entry>
		  <entry>Spalten&uuml;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&uuml;r den Leser</title>

        <para>Oft gilt es, f&uuml;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&auml;lt eine Antwort vom System. Ein Satz
          von speziellen Elementen und Entit&auml;ten unterst&uuml;tzt
          den Autor bei der Auszeichnung solcher Textstellen:</para>
        
	<variablelist>
	  <varlistentry>
	    <term><sgmltag>screen</sgmltag></term>
	    
	    <listitem>
              <para>Gedacht zur Auszeichnung von Bildschirminhalten.
                Im Unterschied zu anderen Elementen werden Leerzeichen
                innerhalb des Elementes <sgmltag>screen</sgmltag>
                unver&auml;ndert &uuml;bernommen.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term><sgmltag>prompt</sgmltag>,
              <literal>&amp;prompt.root;</literal> und
              <literal>&amp;prompt.user;</literal></term>
	    
	    <listitem>
              <para>Eingabeaufforderungen des Rechners
                (Betriebssysten, Shell oder Anwendung) sind ein h&auml;ufig
                auftretender Teil dessen, was der Benutzer auf dem
                Bildschirm zu sehen bekommt. Sie sollten mit
                <sgmltag>prompt</sgmltag> ausgezeichnet werden.</para>

              <para>Ein Spezialfall sind die beiden
                Eingabeaufforderungen der Shell f&uuml;r normale
                Benutzer und den Superuser <username>root</username>.
                Jedesmal wenn auf eine von diesen beiden Nutzerrollen
                hingewiesen werden soll, sollte entweder
                <literal>&amp;prompt.root;</literal> oder
                <literal>&amp;prompt.user;</literal> eingesetzt
                werden. Beide Entit&auml;ten k&ouml;nnen auch
                au&szlig;erhalb von <sgmltag>screen</sgmltag>
                verwendet werden.</para>

	      <note>
                <para><literal>&amp;prompt.root;</literal> und
                  <literal>&amp;prompt.user;</literal> sind
                  FreeBSD-spezifische Erweiterungen der DocBook DTD
                  und nicht in der originalen DocBook DTD
                  enthalten.</para>
	      </note>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term><sgmltag>userinput</sgmltag></term>
	    
	    <listitem>
              <para>Das Element <sgmltag>userinput</sgmltag> ist
                f&uuml;r die Auszeichnung von Benutzereingaben
                gedacht.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	  
	<example>
	  <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>
            und <sgmltag>userinput</sgmltag></title>

	  <programlisting><![ CDATA [<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>]]></programlisting>
	  
	  <para>Darstellung:</para>
	
          <screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>
	</example>
	
	<note>
          <para>Obgleich der Inhalt der Datei
            <filename>foo2</filename> in dem obigen Beispiel angezeigt
            wird, sollte dieser nicht mit
            <sgmltag>programlisting</sgmltag> ausgezeichnet werden.
            Vielmehr sollte <sgmltag>programlisting</sgmltag> einzig
            und allein f&uuml;r die Darstellung von Dateifragmenten
            au&szlig;erhalb von Benutzeraktionen gew&auml;hlt
            werden.</para>
	</note>
      </sect3>
    </sect2>
    
    <sect2>
      <title>Flu&szlig;elemente</title>
      
      <sect3>
	<title>Hervorhebungen</title>

        <para>Wenn es darum geht bestimmte W&ouml;rter oder Textstellen
          hervorzuheben, sollte daf&uuml;r das Element
          <sgmltag>emphasis</sgmltag> verwendet werden. Das so
          ausgezeichnete Text wird dann kursiv oder fett dargestellt;
          im Falle einer Sprachausgabe w&uuml;rde es anders betont
          werden.</para>

        <para>Im Gegensatz zu den HTML mit seinen Elementen
          <sgmltag>b</sgmltag> und <sgmltag>i</sgmltag>, kennt DocBook
          keinen Weg, um diese Darstellung zu
          &auml;ndern<footnote><para>Anmerkung des
              &Uuml;bersetzers: Hier sollte man sich noch einmal ins
              Ged&auml;chtnis rufen, da&szlig; mittels der DocBook DTD nur
              Inhalte ausgezeichnet werden und nicht das Layout
              bestimmt wird.</para></footnote>. Handelt es sich bei
          dem darzustellenden um eine wichtige Information, kann
          alternativ <sgmltag>important</sgmltag> verwendet
          werden.</para>
        
	<example>
	  <title>Das Element <sgmltag>emphasis</sgmltag></title>

	  <programlisting><![ RCDATA [<para>FreeBSD ist zweifelslos <emphasis>das</emphasis> f&uuml;hrende
  Unix-artige Bestriebssystem f&uuml;r die Intel-Plattform.</para>]]></programlisting>
	  
	  <para>Darstellung:</para>

          <para>FreeBSD ist zweifelslos <emphasis>das</emphasis> f&uuml;hrende
            Unix-artige Bestriebssystem f&uuml;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, da&szlig; eine bestimmte Wendung
          im &uuml;bertragenen Sinne zu verstehen ist, kann der
          betreffende Text mit Hilfe des Elementes
          <sgmltag>quote</sgmltag> ausgezeichnet werden. Innerhalb von
          <sgmltag>quote</sgmltag> k&ouml;nnen die meisten der
          normalerweise zur Verf&uuml;gung stehenden Elemente genutzt
          werden.</para>

	<example>
	  <title>Richtig zitieren</title>

	  <programlisting><![ RCDATA [<para>Es sollte immer sichergestellt werden, da&szlig; die Suche die Grenzen
  zwischen <quote>lokaler und &ouml;ffentlicher Administration</quote>
  (RFC 1535) einh&auml;lt.</para>]]></programlisting>

	  <para>Darstellung:</para>

          <para>Es sollte immer sichergestellt werden, das die Suche
            die Grenzen zwischen <quote>lokaler und &ouml;ffentlicher
              Administration</quote> (RFC 1535) einh&auml;lt.</para>
          
	</example>
      </sect3>
      
      <sect3>
	<title>Tasten, Maustasten und Tastenkombinationen</title>

	<para>Das Element <sgmltag>keycap</sgmltag> beschreibt
	  eine bestimmte Taste der Tastatur.
          F&uuml;r die Auszeichnung von Maustasten
          steht analog das Element <sgmltag>mousebutton</sgmltag> zur
          Verf&uuml;gung. Mit Hilfe von <sgmltag>keycombo</sgmltag>
          k&ouml;nnen beliebige Tasten- und Maustastenkombinationen
          beschrieben werden.</para>

        <para>Das Element <sgmltag>keycombo</sgmltag> besitzt ein
          Attribut <literal>action</literal>, dem einer der Werte
          <literal>click</literal>, <literal>double-click</literal>,
          <literal>other</literal>, <literal>press</literal>,
          <literal>seq</literal> oder <literal>simul</literal>
          zugewiesen werden kann. Die letzten beiden Werte deuten an,
          da&szlig; die genannte Kombination nacheinander oder
          gleichzeitig gedr&uuml;ckt werden soll. Die Stylesheets
          f&uuml;gen zwischen die einzelnen Unterelemente von
          <sgmltag>keycombo</sgmltag> <quote>+</quote>-Zeichen
          ein.</para>

	
	<example>
	  <title>Tasten, Maustasten und Tastenkombinationen</title>

          <para>Diese Eingaben zeichnen Sie wie folgt aus:</para>
            
	  <programlisting><![ RCDATA [<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 &Auml;nderungen zu
  speichern, mu&szlig; <keycombo action="seq"><keycap>Esc</keycap>
  <keycap>:</keycap><keycap>q</keycap><keycap>!</keycap>
  </keycombo> eingegeben werden.</para>

<para>Der Fenstermanager ist so konfiguriert, da&szlig; mittels
  <keycombo action="simul"><keycap>Alt</keycap>
  <mousebutton>rechter Maustaste</mousebutton> </keycombo>
   Fenster verschoben werden k&ouml;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
            &Auml;nderungen zu speichern, mu&szlig; <keycombo
              action="seq"><keycap>Esc</keycap>
              <keycap>:</keycap><keycap>q</keycap><keycap>!</keycap>
            </keycombo> eingegeben werden.</para>
          
          <para>Der Fenstermanager ist so konfiguriert, da&szlig; mittels
            <keycombo action="simul"><keycap>Alt</keycap>
              <mousebutton>rechter Maustaste</mousebutton>
            </keycombo>
            Fenster verschoben werden k&ouml;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, da&szlig; 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, da&szlig; 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, da&szlig; die
          von einem Programm (in einem bestimmten Fall)
          akzeptierten Optionen genannt werden m&uuml;ssen.</para>
      
        <para>Schlu&szlig;endlich ist es oft gew&uuml;nscht, zu einem
          Befehl dessen Abschnitt der Manualseiten im
          Unix-&uuml;blichen Stil <quote>Befehl(Zahl)</quote>
          anzugeben.</para>

        <para>Anwendungsnamen k&ouml;nnen mit <sgmltag>application</sgmltag>
          ausgezeichnet werden.</para>

	<para>Befehle k&ouml;nnen zusammen mit der betreffenden
          Hilfeseite &uuml;ber das DocBook-Element
          <sgmltag>citerefentry</sgmltag> ausgezeichnet werden.
          <sgmltag>citerefentry</sgmltag> mu&szlig; zwei weitere
          Elemente enthalten: <sgmltag>refentrytitle</sgmltag>,
          f&uuml;r den Befehlsnamen, und <sgmltag>manvolnum</sgmltag>,
          f&uuml;r die Kategorie der Hilfeseite.</para>

        <para>Diese Art auf Befehle zu verweisen kann sehr
          erm&uuml;dent sein. Daher gibt es einen Satz von
          <link linkend="sgml-primer-general-entities">Allgemeinen
            Entit&auml;ten</link>, der diese Arbeit erleichtert. Er
          ist in der  Datei
          <filename>doc/share/sgml/man-refs.ent</filename> enhalten
          und kann &uuml;ber den folgenden Bezeichner eingebunden
          werden:</para>

        <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting>
        
        <para>Jede Entit&auml;t in dieser Datei ist wie folgt aufgebaut:
          <literal>&amp;man.<replaceable>Hilfeseite</replaceable>.<replaceable>Kategorie</replaceable>;</literal>.</para>

        <para>Der Anfang eines Dokumentes, das diese Entit&auml;ten
          einbindet, k&ouml;nnte so aussehen:</para>

	<programlisting>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
%man; &hellip; ]&gt;</programlisting>

        <para>Um Befehle innerhalb des Flie&szlig;textes auszuzeichen,
          kann das Element <sgmltag>command</sgmltag> genutzt werden.
          Die Optionen eines Befehles k&ouml;nnen mit Hilfe von
          <sgmltag>option</sgmltag> ausgezeichnet werden.</para>

        <!--@todo Den Satz "Vielleicht kann..." umformulieren
            Oliver Fischer, 14. Jan. 2005 -->
        
        <para>Die Unterscheidung zwischen <sgmltag>command</sgmltag>
          und <sgmltag>application</sgmltag> kann schwer sein, und
          manchmal ist die Entscheidung, welches Element das richtige
          ist nicht leicht. Vielleicht kann das folgende Beispiel
          helfen.</para>
        
	<example>
	  <title>Anwendungen, Befehle und Optionen</title>

	  <programlisting><![ RCDATA [<para><application>Sendmail</application> ist der verbreitetste
  UNIX-Mailserver.</para>

<para><application>Sendmail</application> besteht aus den Programmen
  <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, &amp;man.mailq.8;, und &amp;man.newaliases.8;.</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> &uuml;berpr&uuml;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>,
            <citerefentry>
	      <refentrytitle>mailq</refentrytitle>
	      <manvolnum>8</manvolnum>
	    </citerefentry> und
            <citerefentry>
	      <refentrytitle>newaliases</refentrytitle>
	      <manvolnum>8</manvolnum>
	    </citerefentry>.</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> &uuml;berpr&uuml;ft
            werden.</para>
	</example>

	<note>
	  <para>Die Schreibweise
            <literal>&amp;man.<replaceable>Hilfeseite</replaceable>.<replaceable>Kategorie</replaceable>;</literal> 
            ist leichter lesbar.</para>
        </note>
      </sect3>

      <sect3>
	<title>Dateien, Verzeichnisse und Erweiterungen</title>

        <para>Immer wenn in einem Text der Name einer Datei, eines
          Verzeichnisses oder eine Dateierweiterung vorkommt, sollte
          die betreffende Stelle mit dem Element
          <sgmltag>filename</sgmltag> ausgezeichnet werden.</para>

	<example>
	  <title>Das Element <sgmltag>filename</sgmltag></title>

	  <programlisting><![ RCDATA [<para>Die SGML-Quellen des englischen Handbuches befinden
  sich im Verzeichnis <filename>/usr/doc/en/handbook/</filename>. In
  diesem Verzeichnis befindet sich eine Datei
  <filename>handbook.sgml</filename>. Desweiteren sollte sich eine
  Datei mit dem Namen <filenname>Makefile</filename> zusammen mit
  mehreren Dateien mit der Endung <filename>.ent</filename>
  in diesem Verzeichnis befinden.</para>]]></programlisting>

	  <para>Darstellung:</para>
          
          <para>Die SGML-Quellen des englischen Handbuches befinden
            sich im Verzeichnis
            <filename>/usr/doc/en/handbook/</filename>. In diesem
            Verzeichnis befindet sich eine Datei
            <filename>handbook.sgml</filename>. Desweiteren sollte
            sich eine Datei mit dem Namen
            <filename>Makefile</filename> zusammen mit mehreren
            Dateien mit der Endung <filename>.ent</filename> in diesem
            Verzeichnis befinden.</para>

	</example>
      </sect3>

      <sect3>
        <title>Portnamen</title>

	<note>
	  <title>FreeBSD-Erweiterung</title>
	  
	  <para>Die hier genannten Elemente sind Bestandteil der
            FreeBSD-Erweiterung f&uuml;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 Portssammlung in Dokumenten zu verwenden.
          In diesem Fall sollte ebenfalls das Element
          <sgmltag>filename</sgmltag> eingesetzt werden, dabei aber
          dem Element  das  Attribut <literal>role</literal> mit dem
          Wert <literal>package</literal> zugewiesen werden. Da die
          Portssammlung an jeder beliebigen Stelle im Dateisystem
          installiert werden kann, sollte <sgmltag>filename</sgmltag>
          nur die Kategorie und den Namen des Ports enthalten, aber
          nicht das Verzeichnis
          <filename>/usr/ports</filename>.</para>

        <example>
          <title>Portsnamen und das Element <sgmltag>filename</sgmltag></title>

          <programlisting><![ RCDATA [<para>Wenn Sie Ihr Netz und dessen Datenverkehr analysieren
  m&ouml;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&ouml;chten, dann installieren Sie bitte den Port <filename
              role="package">net/ethereal</filename>.</para>
        </example>
      </sect3>

      <sect3>
	<title>Ger&auml;tedateien unterhalb von
          <filename>/dev</filename></title>

	<note>
	  <title>FreeBSD-Erweiterung</title>
	  
	  <para>Die hier genannten Elemente sind Bestandteil der
            FreeBSD-Erweiterung f&uuml;r DocBook und sind nicht in der
            originalen DocBook DTD enthalten.</para>
	</note>

        <para>Wird in einem Dokument Bezug auf Ger&auml;tedateien
          unterhalb von <filename class="directory">dev</filename>
          genommen, dann gibt es zwei M&ouml;glichkeiten diese
          auszuzeichnen. Zum einen kann man sich auf das Ger&auml;t
          beziehen, so wie es unter <filename>/dev</filename> zu
          finden ist, und zum anderen kann man sich auf den
          Ger&auml;tenamen beziehen, wie es innerhalb des Kerns
          verwendet wird. F&uuml;r letztere M&ouml;glichkeit sollte
          das Element <sgmltag>devicename</sgmltag> genutzt
          werden.</para>

        <para>Allerdings besteht nicht immer diese
          Wahlm&ouml;glichkeit. Einige Ger&auml;te, wie zum Beispiel
          Netzwerkkartenm haben keinen Eintrag unter
          <filename>/dev</filename> oder werden anders
          dargestellt.</para>
        
	<example>
	  <title>Ger&auml;tenamen per <sgmltag>devicename</sgmltag>
            auszeichnen</title>

	  <programlisting><![ RCDATA [<para>Unter FreeBSD wird die serielle Daten&uuml;bertragung &uuml;ber
  <devicename>sio</devicename> abgewickelt, das unterhalb von
  <filename>/dev</filename> eine Reihe von Eintr&auml;gen anlegt.
  Zu diesen Eintr&auml;gen beh&ouml;ren beispielsweise
  <filename>/dev/ttyd0</filename> und
  <filename>/dev/cuaa0</filename>.</para>

  <para>Andererseits erscheinen Ger&auml;te wie beispielsweise
    <devicename>ed0</devicename> nicht unterhalb von 
    <filename>/dev</filename>.

  <para>Unter MS-DOS wird das erste Diskettelaufwerk als
    <devicename>a:</devicename> bezeichnet.  FreeBSD
     bezeichnet es als <filename>/dev/fd0</filename>.</para>]]></programlisting>

	  <para>Darstellung:</para>
	    
          <para>Unter FreeBSD wird die serielle Daten&uuml;bertragung
            &uuml;ber <devicename>sio</devicename> abgewickelt, das
            unterhalb von <filename>/dev</filename> eine Reihe von
            Eintr&auml;gen anlegt. Zu diesen Eintr&auml;gen
            beh&ouml;ren beispielsweise
            <filename>/dev/ttyd0</filename> und
            <filename>/dev/cuaa0</filename>.</para>

          <para>Andererseits erscheinen Ger&auml;te wie beispielsweise
            <devicename>ed0</devicename> nicht unterhalb von
            <filename>/dev</filename>.

          <para>Unter MS-DOS wird das erste Diskettelaufwerk als
            <devicename>a:</devicename> bezeichnet. FreeBSD bezeichnet
            es als <filename>/dev/fd0</filename>.</para>
          
	</example>
      </sect3>

      <sect3>
	<title>Rechner, Domains, IP-Adressen und mehr</title>
	
	<note>
	  <title>FreeBSD-Erweiterung</title>
	  
	  <para>Die hier genannten Elemente sind Bestandteil der
            FreeBSD-Erweiterung f&uuml;r DocBook und sind nicht in der
            originalen DocBook DTD enthalten.</para>
	</note>


	<para>Bezeichner f&uuml;r Rechner k&ouml;nnen in Abh&auml;ngigkeit
          der Bezeichnungsweise auf verschiedene Art und Weise
          ausgezeichnet werden. Gemeinsam ist allen, da&szlig; sie
          das Element <sgmltag>hostid</sgmltag>  benutzen. &Uuml;ber das
          Attribut <literal>role</literal> wird die Art des Bezeichners
          genauer bestimmt.</para>
        
	<variablelist>
	  <varlistentry>
            <term>Kein Rollenattribut oder
              <literal>role="hostname"</literal></term>
	    
	    <listitem>
              <para>Ohne Rollenattribut stellt der umschlossene Text
                einen normlen Rechnernamen wie
                <literal>freefall</literal> oder
                <literal>wcarchive</literal> dar. Wenn es
                gew&uuml;nscht ist, kann mittels
                <literal>role="hostname"</literal> explizit angegeben
                werden, da&szlig; 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&auml;lt keinen
                Rechnernamen.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term><literal>role="fqdn"</literal></term>
	    
	    <listitem>
              <para>Vollqualifizierter Domainname wie
                <literal>www.FreeBSD.org</literal>. Enth&auml;lt sowohl
                einen Domainnamen als auch einen Rechnernamen.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>role="ipaddr"</literal></term>
	    
	    <listitem>
              <para>Eine IP-Adresse, meistens als durch Doppelpunkte
                getrenntes Tupel von vier Zahlen dargestellt.</para>
	    </listitem>
	  </varlistentry>

          <varlistentry>
            <term><literal>role="ip6addr"</literal></term>

            <listitem>
              <para>Eine IPv6-Adresse.</para>
            </listitem>
          </varlistentry>
	  
	  <varlistentry>
	    <term><literal>role="netmask"</literal></term>
	    
	    <listitem>
              <para>Eine Netzwerkmaske, dargestellt als ein durch
                Doppelpunkte getrenntes Vierzahlentupel, einer Hexzahl
                oder als ein <literal>/</literal>, dem eine Zahl
                folgt.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term><literal>role="mac"</literal></term>
	    
	    <listitem>
              <para>Eine MAC-Adresse, dargestellt durch zweistellige
                Hexzahlen, die durch Doppelpunkte getrennt
                sind.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	  
	<example>
	  <title><literal>role</literal> und
            <sgmltag>hostid</sgmltag></title>

	  <programlisting><![ RCDATA [<para>Der lokale Rechner kann immer &uuml;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&ouml;ren verschiedene Rechner, inklusive <hostid
    role="fqdn">freefall.FreeBSD.org</hostid> und <hostid
    role="fqdn">bento.FreeBSD.org</hostid>.</para>

  <para>Wenn eine IP-Adresse einer Netzwerkkarte zugeordnet wird,
    was mit der Hilfe von <command>ifconfig</command> geschieht,
    sollte <emphasis>immer</emphasis> die Netzmaske 
    <hostid role="netmask">255.255.255.255</hostid>, die auch
    hexadezimal als <hostid role="netmask">0xffffffff</hostid>
    abgegeben werden kann, benutzt werden.</para>

  <para>Die MAC-Adresse ist f&uuml;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 &uuml;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&ouml;ren
            verschieden Rechner, inklusive <hostid
              role="fqdn">freefall.FreeBSD.org</hostid> und <hostid
              role="fqdn">bento.FreeBSD.org</hostid>.</para>

          <para>Wenn eine IP-Adresse einer Netzwerkkarte zugeordnet
            wird, was mit der Hilfe von <command>ifconfig</command>
            geschieht, sollte <emphasis>immer</emphasis> die Netzmaske
            <hostid role="netmask">255.255.255.255</hostid>, die auch
            hexadezimal als <hostid role="netmask">0xffffffff</hostid>
            abgegeben werden kann, benutzt werden.</para>

          <para>Die MAC-Adresse ist f&uuml;r jede existierende
            Netzwerkkarte auf der Welt eindeutig. Eine typische
            MAC-Adresse ist beispielsweise <hostid
              role="mac">08:00:20:87:ef:d0</hostid>.</para>
	</example>
      </sect3>

      <sect3>
	<title>Benutzernamen</title>
	
	<note>
	  <title>FreeBSD-Erweiterung</title>
	  
	  <para>Die hier genannten Elemente sind Bestandteil der
            FreeBSD-Erweiterung f&uuml;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&ouml;nnen mit dem Element <sgmltag>username</sgmltag>
          ausgezeichnet werden.</para>

	<example>
	  <title>Das Element <sgmltag>username</sgmltag></title>

	  <programlisting><![ RCDATA [<para>F&uuml;r die meisten Administrationsaufgaben m&uuml;ssen
    Sie als <username>root</username> angemeldet sein.</para>]]></programlisting>

	  <para>Darstellung:</para>

	  <para>F&uuml;r die meisten Administrationsaufgaben m&uuml;ssen Sie als
            <username>root</username> angemeldet sein.</para>
          
	</example>
      </sect3>

      <sect3>
	<title>Beschreibung von <filename>Makefile</filename>s</title>
	
	<note>
	  <title>FreeBSD-Erweiterung</title>
	  
	  <para>Die hier genannten Elemente sind Bestandteil der
            FreeBSD-Erweiterung f&uuml;r DocBook und sind nicht in der
            originalen DocBook DTD enthalten.</para>
	</note>

        <para>Zur Beschreibung von Teilen einer Makedatei stehen die
          beiden Elemente <sgmltag>marketarget</sgmltag> und
          <sgmltag>makevar</sgmltag> zur Verf&uuml;gung.
          <sgmltag>maketarget</sgmltag> bezeichnet ein Ziel eines
          <filename>Makefile</filename>s, das als Parameter beim
          Aufruf von <command>make</command> angegeben werden kann.
          <sgmltag>makevar</sgmltag> hingegen bezeichnet eine
          Variable, die entweder in einem
          <filename>Makefile</filename> definiert oder
          <command>make</command> auf der Befehlszeile &uuml;bergeben
          werden kann, um so den Bauprozess zu beeinflussen.</para>
        
      <example>
	  <title><sgmltag>maketarget</sgmltag> und
            <sgmltag>makevar</sgmltag></title>

	  <programlisting><![ RCDATA [<para>Zwei &uuml;bliche Ziele in einem <filename>Makefile</filename>
  sind <maketarget>all</maketarget> und
  <maketarget>clean</maketarget>.</para>
      
<para>&Uuml;blicherweise wird, wenn das Ziel <maketarget>all</maketarget>
  aufgerufen wird, die gesamte Anwendung neu erstellt. Der Aufruf
  des Zieles <maketarget>clean</maketarget> veranla&szlig;t das
  L&ouml;schen aller tempor&auml;ren Dateien (zum Beispiel
  <filename>.o</filename>), die w&auml;hrend der &Uuml;bersetzung erzeugt
  wurden.</para>
      
<para>Das genaue Verhalten von <maketarget>clean</maketarget>
  kann von einer Reihe von Variablen beeinflu&szlig;t werden.
  Stellvertretend seien hier <makevar>CLOBBER</makevar> und
  <makevar>RECURSE</makevar> genannt.</para>]]></programlisting>

	  <para>Darstellung:</para>
          
          <para>Zwei &uuml;bliche Ziele in einem
            <filename>Makefile</filename> sind
            <maketarget>all</maketarget> und
            <maketarget>clean</maketarget>.</para>

          <para>&Uuml;blicherweise wird, wenn das Ziel
            <maketarget>all</maketarget> aufgerufen wird, die gesamte
            Anwendung neu erstellt. Der Aufruf des Zieles
            <maketarget>clean</maketarget> veranla&szlig;t das
            L&ouml;schen aller tempor&auml;ren Dateien (zum Beispiel
            <filename>.o</filename>), die w&auml;hrend der
            &Uuml;bersetzung erzeugt wurden.</para>

          <para>Das genaue Verhalten von
            <maketarget>clean</maketarget> kann von einer Reihe von
            Variablen beeinflu&szlig;t werden. Stellvertretend seien
            hier <makevar>CLOBBER</makevar> und
            <makevar>RECURSE</makevar> genannt.</para>
	</example>
    </sect3>
      
      <sect3>
      <title>Text buchstabengetreu &uuml;bernehmen</title>
      
        <para>F&uuml;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&ouml;nnen
          soll.</para>

      <para>In einigen F&auml;llen ist zu diesem Zwecke
      <sgmltag>programlisting</sgmltag> ausreichend, jedoch nicht
      immer. So ist <sgmltag>programlisting</sgmltag> zum Beispiel
      nicht einsetzbar, wenn es darum geht einen Auszug aus einer
      Datei innerhalb eines Absatzes einzuf&uuml;gen. In solchen F&auml;llen
      sollte das Element <sgmltag>literal</sgmltag> zum Einsatz
      kommen.</para>
      
      <example>
      <title><sgmltag>literal</sgmltag></title>
      
	  <programlisting><![ RCDATA [<para>Die Zeile <literal>maxusers 10</literal> in der
  Kernelkonfigurationsdatei beeinflu&szlig;t die Gr&ouml;&szlig;e vieler
  Systemtabellen und kann als ungef&auml;hr als Richtwert daf&uuml;r
  gelten, wie viele paralle Anmeldungen das System handhaben
  kann.</para>]]></programlisting>
          
	  <para>Darstellung:</para>
	  
          <para>Die Zeile <literal>maxusers 10</literal> in der
            Kernelkonfigurationsdatei beeinflu&szlig;t die Gr&ouml;&szlig;e vieler
            Systemtabellen und kann als ungef&auml;hr als Richtwert daf&uuml;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, da&szlig; der Leser Beispiele,
	  Dateinamen oder Kommandozeilen ver&auml;ndern muss.
          F&uuml;r einen solchen Anwendungsfall
          ist das Element <sgmltag>replaceable</sgmltag> gedacht. Es
          kann <emphasis>innerhalb</emphasis> von anderen Elementen
          genutzt werden, um die Teile auszuzeichnen, die es zu
          ersetzen gilt.</para>
        
	<example>
	  <title>Das Element <sgmltag>replaceable</sgmltag></title>

	  <programlisting><![ RCDATA [<informalexample>
  <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
</informalexample>]]></programlisting>

	  <para>Darstellung:</para>
	  
	  <informalexample>
	    <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
	  </informalexample>

          <para>Dieses Beispiel zeigt, da&szlig; nur der Text mit
            <sgmltag>replaceable</sgmltag> umschlossen werden soll,
            den der Benutzer einzusetzen hat. S&auml;mtlicher anderer
            Text sollte wie &uuml;blich ausgezeichnet werden.</para>

	  <programlisting><![ RCDATA [<para>Die Zeile
  <literal>maxusers <replaceable>n</replaceable></literal>
  in der Kernelkonfigurationsdatei bestimmt die Gr&ouml;&szlig;e vieler Systemtabellen
  und stellt einen groben Richtwert daf&uuml;r dar, wie viele gleichzeitige Anmeldungen
  das System unterst&uuml;tzt.</para>

<para>F&uuml;r einen Arbeitsplatzrechner stellt <literal>32</literal> einen guten
  Wert f&uuml;r <replaceable>n</replaceable> dar.</para>]]></programlisting>
          
	  <para>Darstellung:</para>

          <para>Die Zeile <literal>maxusers
              <replaceable>n</replaceable></literal> in der
            Kernelkonfigurationsdatei bestimmt die Gr&ouml;&szlig;e
            vieler Systemtabellen und stellt einen groben Richtwert
            daf&uuml;r dar, wie viele gleichzeitige Anmeldungen das
            System unterst&uuml;tzt.</para>

          <para>F&uuml;r einen Arbeitsplatzrechner stellt
            <literal>32</literal> einen guten Wert f&uuml;r
            <replaceable>n</replaceable> dar.</para>          
	</example>
      </sect3>

      <sect3>
        <title>Fehlermeldungen des Systems darstellen</title>

        <para>In manchen F&auml;llen kann es n&ouml;tig sein,
          Fehlermeldungen darzustellen, die von FreeBSD erzeugt werden
          k&ouml;nnen. F&uuml;r solche F&auml;lle ist das Element
          <sgmltag>errorname</sgmltag> vorgesehen.</para>
        
        <example>
          <title>Das Element <sgmltag>errorname</sgmltag></title>

	  <programlisting><![ RCDATA [ <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, da&szlig; sich die hier beschriebenen
          Mechanismen noch &auml;ndern werden.</para>

        <para>F&uuml;r die Verwendung von Grafiken ist es notwendig,
          den Port <filename
            role="package">graphics/ImageMagick</filename>
          zus&auml;tzlich zu installieren, da er
          <emphasis>nicht</emphasis> vom Port <filename
            role="package">textproc/docproj</filename> mitinstalliert
          wird.</para>

        <para>Das beste Beispiel f&uuml;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&auml;ngt. Es empfiehlt sich, den Artikel in
          verschiedenen Ausgabeformaten zu erzeugen, da man so sehen
          kann, wie die Grafiken in Abh&auml;ngigkeit vom
          Ausgabemedium angeordnet werden.</para>
      </important>
      
      <sect3>
	<title>Unterst&uuml;tze Grafikformate</title>

        <para>Zur Zeit werden nur zwei Grafikformate unterst&uuml;tzt.
          Welches von beiden Formaten zum Einsatz kommen sollte,
          h&auml;ngt von der Art der Grafik ab.</para>

        <para>F&uuml;r Bilder, die vorrangig Vektorelemente wie
          Netzwerkdiagramme, Zeitlinien und &auml;hnliches beinhalten,
          sollte Encapsulated Postscript als Format gew&auml;hlt
          werden. Wichtig ist es in diesem Fall, da&szlig; die
          Grafikdatei die Endung <filename>.eps</filename> hat.
          F&uuml;r Bitmapgrafiken, wie zum Beispiel Bildschirmfotos,
          steht das  Portable Network Grafic Format zur
          Verf&uuml;gung. In diesem Fall, sollte die Grafikdatei immer
          die Endung <filename>.png</filename> haben.</para>

        <para>In das CVS-Archiv sollten <emphasis>nur</emphasis>
          Grafiken in diesen beiden Formaten &uuml;bernommen
          werden.</para>

        <para>Es sollte darauf sehr darauf geachtet werden, das
          richtige Format f&uuml;r das richtige Bild zu w&auml;hlen.
          Erwartungsgem&auml;&szlig; wird es Dokumente geben, die eine
          Mischung aus PNG- und EPS-Grafiken enthalten. In solchen
          F&auml;llen, stellen die Makedateien die Verwendung des
          richtigen Formats in Abh&auml;ngigkeit vom Ausgabeformat
          sicher. <emphasis>Deshalb sollte die gleiche Grafik niemals
            in zwei unterschiedlichen Formaten in das CVS-Archiv
            &uuml;bernommen werden</emphasis>.</para>

	<important>
          <para>Es ist absehbar, da&szlig; das Dokumentationsprojekt
            in Zukunft das Scalable Vector Graphic-Format (SVG) als
            Standardformat f&uuml;r Vektorgrafiken &uuml;bernehmen
            wird. Zum jetzigen Zeitpunkt ist dieser Wechsel noch nicht
            m&ouml;glich, da der Stand der jetzigen SVG-Anwendungen
            noch nicht den daf&uuml;r notwendigen Erfordernissen
            entspricht.</para>
	</important>

      </sect3>

      <sect3>
	<title>DocBook-Elemente f&uuml;r den Grafikeinsatz</title>

        <para>Das Auszeichnen von Bildern mittels DocBook ist relativ
          einfach. Zuerst wird ein
          <sgmltag>mediaobject</sgmltag>-Element eingef&uuml;gt, das
          als Container f&uuml;r medienspezifische Elemente fungieren
          kann. F&uuml;r die Zwecke des FDPs sind das die Elemente
          <sgmltag>imageobject</sgmltag> und
          <sgmltag>textobject</sgmltag>.</para>

        <para>In das <sgmltag>mediaobject</sgmltag>-Element sollten
          ein Element vom Typ <sgmltag>imageobject</sgmltag> und zwei
          <sgmltag>textobject</sgmltag>-Elemente eingef&uuml;gt
          werden. Das <sgmltag>imageobject</sgmltag>-Element verweist
          auf die eigentliche Grafikdatei. Dabei ist allerdings nur
          der Dateipfad ohne Erweiterung anzugegeben. Die
          <sgmltag>textobject</sgmltag>-Elemente werden daf&uuml;r
          genutzt, Texte aufzunehmen, die dem Leser anstelle des
          Bildes oder zusammen mit dem Bild angezeigt werden.</para>

        <para>Dies kann unter zwei Umst&auml;nden geschehen:</para>

        <itemizedlist>
	  <listitem>
            <para>Wenn ein Dokument als HTML-Datei durch einem Browser
              angezeigt wird. In diesem Falle mu&szlig; 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 &uuml;ber die Grafik
              f&uuml;hrt.</para>
	  </listitem>

	  <listitem>
            <para>Wenn das Dokument als Textdatei gelesen wird. Da in
              einer Textdatei keine Grafiken angezeigt werden k&ouml;nnen,
              sollte es f&uuml;r die Grafik eine Textentsprechung geben,
              die alternativ angezeigt werden kann.</para>
	  </listitem>
	</itemizedlist>

        <para>Das folgende Beispiel soll das bisher geschriebene
          illustrieren. Angenommen es liegt eine einzubindene Grafik
          in der Datei <filename>bild1</filename> vor, die  die
          Darstellung eines As in einem Rechteck enth&auml;lt. Die
          ASCII-Alternative k&ouml;nnte so ausgezeichnet werden:</para>

	<programlisting>&lt;mediaobject>
  &lt;imageobject>
    &lt;imagedata fileref="bild1"> <co id="co-image-ext">
  &lt;/imageobject>
  &lt;textobject>
    &lt;literallayout class="monospaced">+ - - - - - - - - - - - - - - -+ <co id="co-image-literal">
|       A       |
+- - - - - - - - - - - - - - -+&lt;/literallayout>
  &lt;/textobject>
  &lt;textobject>
    &lt;phrase>Ein Bild&lt;/phrase> <co id="co-image-phrase">
  &lt;/textobject>
&lt;/mediaobject></programlisting>

	<calloutlist>
	  <callout arearefs="co-image-ext">
            <para>Innerhalb vom Element <sgmltag>imageobject</sgmltag>
              befindet sich ein Element <sgmltag>imagedata</sgmltag>,
              welches mit Hilfe des Attributes
              <literal>fileref</literal> den Namen der Grafikdatei
              (ohne Erweiterung) angibt. Die Bestimmung der
              Dateierweiterung wird von den Stylesheets
              &uuml;bernommen.</para>            
	  </callout>

	  <callout arearefs="co-image-literal">
            <para>Das erste <sgmltag>textobject</sgmltag>-Element
              enth&auml;lt ein <sgmltag>literallayout</sgmltag>-Element,
              dessen Attribut <literal>class</literal> den Wert
              <literal>monospaced</literal> zugewiesen bekommt. Der
              Inhalt dieses Elements wird genutzt, wenn das Dokument
              in Textform ausgegeben wird. An dieser Stelle hat der
              Autor die M&ouml;glichkeit seine
              <quote>Textzeichenk&uuml;nste</quote> unter Beweis zu
              stellen.</para>              

            <para>Wichtig ist, da&szlig; die erste und die letzte
              Zeile sich gleichauf mit dem &ouml;ffenden und dem
              schlie&szlig;enden Tag befindet. Dadurch wird
              sichergestellt, da&szlig; keine unn&ouml;tigen
              Leerzeichen in die Ausgabe aufgenommen werden.</para>
	  </callout>

	  <callout arearefs="co-image-phrase">
            <para>Das zweite <sgmltag>textobject</sgmltag>-Element
              sollte lediglich ein <sgmltag>phrase</sgmltag>-Element
              enthalten. Wird das Dokument nach HTML konvertiert, wird
              dessen Inhalt f&uuml;r das Attribut
              <literal>alt</literal> des <sgmltag>img</sgmltag>-Tags
              verwendet.</para>
	  </callout>
	</calloutlist>
      </sect3>

      <sect3>
	<title>Die <filename>Makefile</filename>-Eintr&auml;ge</title>

        <para>Alle in einem Dokument verwendeten Grafiken m&uuml;ssen in
          dem zugeh&ouml;rigen Makefile in der Variable
          <makevar>IMAGES</makevar> enthalten sein.
          <makevar>IMAGES</makevar> sollte immer die Namen der
          <emphasis>Quellgrafiken</emphasis> enthalten. Werden in
          einem Dokument beispielsweise die drei Grafiken
          <filename>bild1.eps</filename>,
          <filename>bild2.png</filename> und
          <filename>bild3.png</filename> referenziert, sollte das
          <filename>Makefile</filename> die folgende Zeile
          enthalten:</para>

        <programlisting>&hellip;
IMAGES= bild1.eps bild2.png bild3.png
&hellip;</programlisting>

	<para>Eine andere M&ouml;glichkeit w&auml;re:</para>

	<programlisting>&hellip;
IMAGES=  bild1.eps
IMAGES+= bild2.png
IMAGES+= bild3.png
&hellip;</programlisting>

        
        <para>Es kann nicht oft genug betont werden: Welche
          Grafikdateien f&uuml;r das zu erzeugende Dokument ben&ouml;tigt
          werden, wird von dem Makefiles bestimmt.
          <makevar>IMAGES</makevar> darf nur die Originaldateien
          enthalten.</para>
      </sect3>

      <sect3>
	<title>Grafiken und Kapitel in Unterverzeichnissen</title>

	<para>Wenn Sie Ihre Dokumentation in mehrere kleine
	  Dateien aufspalten (siehe
	  <xref linkend="sgml-primer-include-using-gen-entities">),
	  m&uuml;ssen Sie sorgf&auml;ltig vorgehen.</para>

        <para>Angenommen es handelt sich um ein Buch, dessen drei
          Kapitel in separaten Verzeichnissen angelegt wurden
          (<filename>kapitel1/kapitel.sgml</filename>,
          <filename>kapitel2/kapitel.sgml</filename> und
          <filename>kapitel3/kapitel.sgml</filename>). Enthalten die
          Kapitel Grafiken, empfiehlt es sich, diese in den gleichen
          Verzeichnisses abzulegen, wie die Kapitel selbst. In diesem
          Falle gilt es jedoch zu beachten, da&szlig; die Pfade der
          Grafikdateien in der Variable <makevar>IMAGES</makevar> und
          in den <sgmltag>imagedata</sgmltag>-Elementen immer auch den
          Verzeichnisnamen mitenthalten.</para>

        <para>Soll beispielsweise die Datei
          <filename>kapitel1/bild1.png</filename> in das in
          <filename>kapitel1/kapitel.sgml</filename> enthaltene
          Kapitel eingebunden werden, sollte die so erfolgen:</para>
        
	<programlisting>&lt;mediaobject>
  &lt;imageobject>
    &lt;imagedata fileref="kapitel1/bild1"> <co id="co-image-dir">
  &lt;/imageobject>

  &hellip;            
&lt;/mediaobject></programlisting>
	
	<calloutlist>
	  <callout arearefs="co-image-dir">
            <para><literal>fileref</literal> mu&szlig; den
              Datei- und den Verzeichnisnamen enthalten.</para>
          </callout>
	</calloutlist>

        <para>Das <filename>Makefile</filename> mu&szlig; dementsprechend
          die Zeile
        
	<programlisting>&hellip;
IMAGES=  kapitel1/bild1.png
&hellip;</programlisting>

          enthalten.</para>

        <para>Wird dies beachtet, sollte es zu keinen Problemen
          kommen.</para>
      </sect3>
    </sect2>
    
    <sect2>
      <title>Querverweise</title>

      <note>
	<para>Querverweise sind auch Flu&szlig;elemente.</para>
      </note>

      <sect3>
	<title>Querverweise innerhalb eines Dokumentes</title>


        <para>Um innerhalb eines Dokumentes Verweise anzulegen, mu&szlig;
          angegeben werden, von welcher Textstelle aus wohin verwiesen
          werden soll.</para> 

        <para>Jedes DocBook-Element besitzt ein Attribut
          <literal>id</literal>, &uuml;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&auml;llen werden Querverweise nur zu
          Kapiteln gesetzt. Die <sgmltag>chaper</sgmltag>- und
          <sgmltag>sect*</sgmltag>-Elemente sollten aus diesem Grunde
          ein gesetztes <literal>id</literal>-Attribut
          besitzen.</para>

	<example>
	  <title><sgmltag>chapter</sgmltag> und <sgmltag>section</sgmltag>
            mit dem Attribut <literal>id</literal></title>
	  <!--<title><literal>id on chapters and sections</literal></title>-->

	  <programlisting><![ RCDATA [<chapter id="kapitel1">
  <title>Einf&uuml;hrung</title>

  <para>Das ist eine Einf&uuml;hrung. Sie enth&auml;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&uuml;r das Attribut <literal>id</literal>
          sollte immer ein selbsterkl&auml;render Bezeichner gew&auml;hlt
          werden. Zudem ist es notwendig, da&szlig; dieser Bezeichner
          innerhalb des Dokumentes eindeutig ist. Im obigen Beispiel
          wurde der Bezeichner f&uuml;r das Unterkapitel gebildet,
          indem der Bezeichner des &uuml;bergeordneten Kapitels um den
          Titel des Unterkapitels erweitert wurde. Diese
          Vorgehensweise hilft sicherzustellen, da&szlig; 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&auml;llen kann an der Stelle, auf die verwiesen werden
          soll, das Element <sgmltag>anchor</sgmltag> mit gesetztem
          Attribut <literal>id</literal> eingef&uuml;gt werden.
          <sgmltag>anchor</sgmltag> kann selber keinen weiteren Inhalt
          aufnehmen.</para>
        
	<example>
	  <title>Querverweise und das Element
            <sgmltag>anchor</sgmltag></title>

	  <programlisting><![ RCDATA [<para>Dieser Absatz enth&auml;lt ein
  <anchor id="absatz1">Ziel f&uuml;r Querverweise, was jedoch keine
  Auswirkung auf dessen Darstellung hat.</para>]]></programlisting>
	</example>
          
        <para>Zum Anlegen des eigentlichen Querverweises selbst kann
          eines der beiden Elemente <sgmltag>xref</sgmltag> oder
          <sgmltag>link</sgmltag> genutzt werden. Beide besitzen das
          Attribut <literal>linkend</literal>, dem der
          <literal>id</literal>-Wert des Verweiszieles zugewiesen
          wird. Ob sich das Ziel vor oder nach dem Verweis befindet,
          spielt keine Rolle.</para>

        <para><sgmltag>xref</sgmltag> und <sgmltag>link</sgmltag>
          unterscheiden sich jedoch hinsichtlich der Art und Weise,
          auf die der Text erzeugt wird, auf dem der Querverweis
          liegt. Kommt <sgmltag>xref</sgmltag> zum Einsatz, hat der
          Autor keine Kontrolle dar&uuml;ber &ndash; der Text wird
          automatisch f&uuml;r ihn erzeugt.</para>

        
	<example>
	  <title>Einsatz von <sgmltag>xref</sgmltag></title>

          <!-- @todo Das englische Original sollte um
                     einen Link zu dem Beispiel erweitert werden. -->
          <para>F&uuml;r dieses Beispiel wird davon ausgegangen, da&szlig; sich
            folgendes Textfragment irgendwo innerhalb eines Dokumentes
            auftaucht, da&szlig; das vorherige
            <literal>id</literal>-Beispiel enth&auml;lt.</para>

            
	  <programlisting><![ RCDATA [<para>Weitere Informationen gibt
  es im <xref linkend="kapitel1">.</para>

<para>Genauere Informationen k&ouml;nnen im 
  <xref linkend="kapitel1-unterkapitel1"> gefunden werden.</para>]]></programlisting>

          <para>Der Verweistext wird automatisch von den Stylesheets
            erzeugt und so hervorgehoben, da&szlig; ersichtlich ist,
            da&szlig; es sich bei dem Text um einen Verweis
            handelt.</para>
          
	  <blockquote>
	    <para>Weitere Informationen k&ouml;nnen in der
                <emphasis>Einf&uuml;hrung</emphasis> gefunden
                werden.</para>

              <para>Genauere Informationen k&ouml;nnen im
                <emphasis>Unterkapitel 1</emphasis> gefunden
                werden.</para>
	  </blockquote>
	</example>

        <para>Der Text, auf dem der HTML-Link f&uuml;r den Querverweis
          liegt, wurde von den Kapitel&uuml;berschriften
          &uuml;bernommen.</para>

	<note>
          <para>Das bedeutet, da&szlig; es <emphasis>nicht
              m&ouml;glich</emphasis> ist, mit der Hilfe von
            <sgmltag>xref</sgmltag> einen Querverweis zu einer mit
            <sgmltag>anchor</sgmltag> gekennzeichneten Stelle
            anzulegen. Da <sgmltag>anchor</sgmltag>  keinen Inhalt
            aufnehmen kann, k&ouml;nnen die Stylesheets nicht
            automatisch einen Text f&uuml;r den Verweis
            erzeugen.</para>
        </note>

        <para>M&ouml;chte man selber den f&uuml;r den Verweis
          benutzten Text bestimmen k&ouml;nnen, sollte das Element
          <sgmltag>link</sgmltag> verwendet werden. Im Gegensatz zu
          <sgmltag>xref</sgmltag> kann <sgmltag>link</sgmltag> Inhalt
          aufnehmen, der dann f&uuml;r den Verweis verwendet
          wird.</para>

        
	<example>
	  <title><sgmltag>link</sgmltag> beutzen</title>

          <para>F&uuml;r dieses Beispiel wird davon ausgegangen, da&szlig;
            es sich in dem Dokument befindet, das auch
            das <literal>id</literal>-Beispiel enth&auml;lt.</para>

	  <programlisting><![ RCDATA [<para>Weitere Informationen k&ouml;nnen
  im <link linkend="kapitel1">ersten Kapitel</link> gefunden
  werden.</para>

<para>Genauere Informationen k&ouml;nnen in        
  <link linkend="kapitel1-unterkapitel1">diesem</link> Kapitel
  gefunden werden.</para>]]></programlisting>

          <para>Aus diesem SGML-Fragment w&uuml;rden die Stylesheets
            folgendes generieren (der hervorgehobene Text deutet den
            erzeugten Verweis an):</para>

	  <blockquote>
            <para>Weitere Informationen k&ouml;nnen im <emphasis>ersten
                Kapitel</emphasis> gefunden werden.</para>

            <para>Genauere Informationen k&ouml;nnen in
              <emphasis>diesem</emphasis> Kapitel gefunden
              werden.</para>
          </blockquote>
	</example>
	
	<note>
          <para>Das letzte Beispiel ist schlecht. Es sollten niemals
            W&ouml;rter wie <quote>dieses</quote> oder
            <quote>hier</quote> als Linktext benutzt werden. Solche
            W&ouml;rter zwingen den Leser dazu, den Kontext des
            Verweises zu lesen, um zu verstehen, wohin der Verweis
            f&uuml;hrt.</para>
	</note>

	<note>
          <para>Mit dem Element <sgmltag>link</sgmltag>
            <emphasis>kann</emphasis> auf mit
            <sgmltag>anchor</sgmltag> gekennzeichnete Stellen im
            Dokument verwiesen werden, da der Inhalt von
            <sgmltag>link</sgmltag> als Text f&uuml;r den Querverweise
            genutzt wird.</para>
	</note>
      </sect3>

      <sect3>
	<title>Verweise auf Dokumente im WWW</title>

        <para>Das Anlegen von Verweisen auf externe Dokumente ist
          wesentlich einfacher &ndash; solange die URL des zu
          referenzierenden Dokumentes bekannt ist. Um von einem
          bestimmten Textabschnitt auf das gew&uuml;nschte externe
          Dokument zu verweisen, mu&szlig; die jeweilige Stelle mit
          dem Element <sgmltag>ulink</sgmltag> ausgezeichnet werden.
          Mittels des Attributes <literal>url</literal> kann die
          Adresse des Zieldokumentes angegeben werden. Bei der
          Umformung des Quelldokumentes in die verschiedenen
          Ausgabeformate wird der sich zwischen Start- und Endtag
          befindliche Text f&uuml;r den Verweis &uuml;bernommen, den
          der Leser aufrufen kann.</para>
        
        
	<example>
	  <title>Verweise mit <sgmltag>ulink</sgmltag></title>

          <!-- @todo Welchen Fall erforder anstatt? -->
	  <programlisting><![ RCDATA [<para>Nat&uuml;rlich ist es m&ouml;glich, anstatt diesen Text
  weiterzulesen, sofort die
  <ulink url="../../../../index.html">FreeBSD-Homepage</ulink>
  aufzurufen.<para>]]></programlisting>

	  <para>Darstellung:</para>

	  <para>Nat&uuml;rlich ist es m&ouml;glich, anstatt diesen Text
            weiterzulesen, sofort die <ulink
              url="../../../../index.html">FreeBSD-Homepage</ulink>
            aufzurufen.<para>

	  
	</example>
      </sect3>
    </sect2>
  </sect1>
</chapter>


<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->
