       Die Fibel fu:r neue Mitarbeiter des FreeBSD-Dokumentationsprojekts

   Version: 43184

   Copyright (c) 1998-2012 The FreeBSD Documentation Project

   Copyright (c) 1998-2012 The FreeBSD German Documentation Project

   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.

  Wichtig:

   THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "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 THE FREEBSD DOCUMENTATION
   PROJECT 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.

   2013-11-13 von hrs.
   Zusammenfassung

   Vielen Dank fu:r Ihr Interesse und Ihre Mitarbeit an der
   FreeBSD-Dokumentation. Jeder Beitrag ist fu:r uns sehr wichtig.

   In dieser Fibel wird von der eingesetzten Software bis hin zu den
   Vorstellungen des FreeBSD-Dokumentationsprojekts alles behandelt, was Sie
   wissen mu:ssen, wenn Sie sich am FreeBSD-Dokumentationsprojekt beteiligen
   wollen.

   Bitte beachten Sie, dass diese Fibel jederzeit unter Bearbeitung und noch
   nicht vollsta:ndig ist.

   [ einzelne Abschnitte / komplettes Dokument ]

     ----------------------------------------------------------------------

   Inhaltsverzeichnis

   Benutzungshinweise

                1. Die Eingabeaufforderungen

                2. Typographische Festlegungen

                3. Anmerkungen, Tipps, wichtige Hinweise, Warnungen und
                Beispiel

                4. Danksagungen

   1. U:berblick

                1.1. Die FreeBSD-Dokumentationsreihe

                1.2. Bevor es losgeht

                1.3. Der Schnellstart

   2. Die Werkzeuge

                2.1. Notwendige Werkzeuge

                2.2. Optionale Werkzeuge

   3. Die XML-Fibel

                3.1. U:berblick

                3.2. Von Elementen, Tags und Attributen

                3.3. Die DOCTYPE-Deklaration

                3.4. Die Ru:ckkehr zu SGML

                3.5. Kommentare

                3.6. Entita:ten

                3.7. Dateien mit Entita:ten einbinden

                3.8. Markierte Bereiche

                3.9. Schlussbemerkung

   4. XML-Dokumente erstellen

                4.1. XHTML

                4.2. Die DocBook DTD

   5. Stylesheets

                5.1. DSSSL

                5.2. CSS

   6. Verzeichnisstruktur unter doc/

                6.1. doc/ als ho:chste Ebene

                6.2. Die Verzeichnisse Sprache.Kodierung/

                6.3. Dokumentenspezifische Informationen

   7. Die Erzeugung der Zieldokumente

                7.1. Fu:r den Bau der FreeBSD-Dokumentation beno:tigte
                Werkzeuge

                7.2. Die Makefiles des Dokumentationsbaums verstehen

                7.3. Make-Includes des FreeBSD Documentation Projects

   8. Die Webseite

                8.1. Vorbereitung

                8.2. Die Webseiten bauen

                8.3. Installieren der Webseiten auf Ihrem Server

                8.4. Umgebungsvariablen

   9. U:bersetzungen

   10. Der Schreibstil

                10.1. Anleitungen fu:r einen korrekten Schreibstil

                10.2. Ha:ufig verwendete Wo:rter

   11. sgml-mode und Emacs

   12. Weiterfu:hrende Quellen

                12.1. Das FreeBSD-Dokumentationsprojekt

                12.2. XML

                12.3. HTML

                12.4. DocBook

                12.5. Das Linux-Dokumentationsprojekt

   A. Beispiele

                A.1. DocBook-Buch (book)

                A.2. DocBook-Artikel (article)

                A.3. Ausgabeformate erzeugen

   Stichwortverzeichnis

   Liste der Beispiele

   1. Ein Beispiel

   3.1. Verwendung eines Elements (Start- und Endtag)

   3.2. Verwendung eines Elements (nur Starttag)

   3.3. Verschachtelte Elemente: em

   3.4. Elemente mit Attributen nutzen

   3.5. Attribute mit einfachen Anfu:hrungszeichen

   3.6. .profile, fu:r sh(1) und bash(1) Benutzer

   3.7. .cshrc, fu:r csh(1)- und tcsh(1)-Benutzer

   3.8. Beispiele fu:r Kommentare in SGML

   3.9. Fehlerhafte SGML-Kommentare

   3.10. Allgemeine Entita:ten festlegen

   3.11. Parameterentita:ten festlegen

   3.12. Dateien mit Allgemeinen Entita:ten einbinden

   3.13. Dateien mit Parameterentita:ten einbinden

   3.14. Aufbau eines markierten Bereiches

   3.15. CDATA als Inhaltsmodell fu:r markierte Bereiche

   3.16. Anwendung von INCLUDE und IGNORE in markierten Abschnitten

   3.17. Kontrolle von markierten Bereichen u:ber Parameterentita:ten

   4.1. Die Struktur eines XHTML-Dokumentes

   4.2. h1, h2...

   4.3. Falsche Verschachtelung von U:berschriften

   4.4. Absa:tze mit dem Element p

   4.5. Blockzitat

   4.6. Listen mit ul und ol erstellen

   4.7. Definitionslisten mit dl erstellen

   4.8. Vorformatierten Text mit pre erstellen

   4.9. Einfache Tabelle mit table

   4.10. Anwendung des Attributes rowspan

   4.11. Anwendung des Attributes colspan

   4.12. Gemeinsame Anwendung der Attrbute rowspan und colspan

   4.13. Text mit em und strong hervorheben

   4.14. Nicht-proportionale Schrift mit tt

   4.15. <a href="..."> benutzen

   4.16. Anwendung von <a id="...">

   4.17. Auf einen Abschnitt eines anderen Dokumentes verweisen

   4.18. Buchvorlage book mit bookinfo

   4.19. Artikelvorlage article mit articleinfo

   4.20. Ein einfaches Kapitel

   4.21. Ein leeres Kapitel

   4.22. Unterkapitel

   4.23. Absatz mit para

   4.24. blockquote

   4.25. warning

   4.26. itemizedlist, orderedlist und procedure

   4.27. programlisting

   4.28. Das co- und das calloutlist-Element

   4.29. Tabellen mittels informaltable auszeichnen

   4.30. Tabelle mit Attribut frame="none"

   4.31. screen, prompt und userinput

   4.32. Das Element emphasis

   4.33. Richtig zitieren

   4.34. Tasten, Maustasten und Tastenkombinationen

   4.35. Anwendungen, Befehle und Optionen

   4.36. Das Element filename

   4.37. Portsnamen und das Element filename

   4.38. Gera:tenamen per devicename auszeichnen

   4.39. role und hostid

   4.40. Das Element username

   4.41. maketarget und makevar

   4.42. literal

   4.43. Das Element replaceable

   4.44. Das Element errorname

   4.45. chapter und section mit dem Attribut id

   4.46. Querverweise und das Element anchor

   4.47. Einsatz von xref

   4.48. link beutzen

   4.49. Verweise mit ulink

   A.1. Ein DocBook-Buch (book)

   A.2. Ein DocBook-Artikel (article)

   A.3. Ein DocBook-Dokument in eine einzelne HTML-Datei umwandeln

   A.4. Ein DocBook-Dokument in mehrere kleine HTML-Dateien umwandeln

   A.5. Ein DocBook-Dokument nach Postscript umwandeln

   A.6. Eine PDF-Datei aus einem DocBook-Dokument erzeugen

                               Benutzungshinweise

   Inhaltsverzeichnis

   1. Die Eingabeaufforderungen

   2. Typographische Festlegungen

   3. Anmerkungen, Tipps, wichtige Hinweise, Warnungen und Beispiel

   4. Danksagungen

1. Die Eingabeaufforderungen

   Die folgende Tabelle zeigt die normale Eingabeaufforderung des Systems und
   die Eingabeaufforderung des Superusers. Die in diesem Buch vorkommenden
   Beispiele benutzen die jeweilige Eingabeaufforderung, um zu zeigen, unter
   welchem Benutzer die Beispiele ausgefu:hrt werden sollten.

                 Benutzer                        Eingabeaufforderung          
   Normaler Benutzer                    %                                     
   Superuser                            #                                     

2. Typographische Festlegungen

   Um die Lesbarkeit zu erho:hen, werden in diesem Dokument die im folgenden
   genannten typographischen Festlegungen verwendet:

                  Bedeutung                             Beispiel              
   Kommandonamen                           Geben Sie ls -a ein, um alle       
                                           Dateien anzuzeigen.                
   Datei- und Verzeichnisnamen             Bearbeiten Sie .login.             
   Bildschirmein- und ausgaben             You have mail.                     
   Referenzen auf Hilfeseiten              Mit su(1) ko:nnen Sie sich als ein 
                                           anderer Benutzer anmelden.         
   Benutzer- und Gruppennamen              Ich bin root, ich darf das.        
   Hervorhebungen                          Hier mu:ssen Sie vorsichtig sein.  
   Argumente auf der Kommandozeile, die    Dateien ko:nnen Sie mit dem Befehl 
   durch existierende Namen, Dateien oder  rm Dateiname lo:schen.             
   Variablen ersetzt werden mu:ssen        
   Umgebungsvariablen                      $HOME ist Ihr Benutzerverzeichnis. 

3. Anmerkungen, Tipps, wichtige Hinweise, Warnungen und Beispiel

   An einigen Stellen innerhalb dieses Buchs werden wichtige oder nu:tzliche
   Hinweise gegeben, die besonders hervorgehoben sind. Hier ein kurzer
   U:berblick u:ber die verwendeten Darstellungen.

  Anmerkung:

   Anmerkungen werden so dargestellt. Sie enthalten Informationen die Sie nur
   zu lesen brauchen, wenn Sie direkt davon betroffen sind.

  Tipp:

   Tipps sind Informationen, die vielleicht hilfreich sein ko:nnten oder
   aufzeigen, wie bestimmte Dinge einfacher zu bewerkstelligen sind.

  Wichtig:

   Besonders wichtige Punkte werden so hervorgehoben. Meist enthalten sie
   Hinweise auf vielleicht zusa:tzlich auszufu:hrende Schritte oder Dinge,
   die besonders zu beachten sind.

  Warnung:

   Warnungen werden wie dieser Abschnitt dargestellt und weisen auf mo:gliche
   Scha:den hin, die entstehen ko:nnen, falls die beschriebenen Schritte
   nicht genau befolgt oder Hinweise nicht beachtet werden. Die Palette der
   mo:glichen Scha:den reicht von Hardwarescha:den bis hin zu
   Datendatenverlust durch ein versehentliches Lo:schen von wichtigen Dateien
   oder ganzen Verzeichnissen.

   Beispiel 1. Ein Beispiel

   Beispiele, die so wie hier dargestellt werden, enthalten meist kleine
   U:bungen, die nachvollzogen werden sollten, um das vorher beschriebene
   besser zu verinnerlichen oder mit den erzeugten Ausgaben vertraut zu
   werden.

4. Danksagungen

   Ich mo:chte mich bei Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn
   und Christopher Maden bedanken, die sich die Zeit genommen haben, die
   fru:hen Entwu:rfe dieses Dokuments zu lesen und viele hilfreiche Hinweise
   und Ratschla:ge gegeben haben.

                             Kapitel 1. U:berblick

   Inhaltsverzeichnis

   1.1. Die FreeBSD-Dokumentationsreihe

   1.2. Bevor es losgeht

   1.3. Der Schnellstart

   Herzlich Willkommen beim FreeBSD-Dokumentationsprojekt. Qualitativ
   hochwertige Dokumentation ist ein wichtiger Erfolgsfaktor und sehr
   bedeutend fu:r die Verbreitung von FreeBSD. Die wichtigste Quelle dafu:r
   ist das FreeBSD-Dokumentationsprojekt (FDP). Jeder Beitrag, der zu diesem
   Projekt geleistet wird, ist ungemein wertvoll.

   Es ist das Anliegen dieser Fibel, den Leser mit dem FDP vertraut zu machen
   und zu erkla:ren, wie das FDP organisiert ist, wie man selber Dokumente
   erstellt und an das FDP einreicht und wie die verfu:gbaren Werkzeuge
   effektiv beim Schreiben eingesetzt werden ko:nnen.

   Wie jedes Open-Source-Projekt, ist auch das FDP auf die Mithilfe vieler
   angewiesen. Deshalb ist jeder herzlich eingeladen mitzuarbeiten. Die
   dafu:r erforderlichen Voraussetzungen sind gering und es gibt keine
   Verpflichtung eine bestimmte Menge an Dokumenten pro Monat oder Jahr
   beizusteuern. Das Einzige, was Sie tun mu:ssen, ist sich auf der
   Mailingliste FreeBSD documentation project einzutragen.

   Nach dem Lesen der FDP-Fibel sollte man wissen:

     * welche Dokumente durch das FDP betreut werden,

     * wie man SGML-Dokumente liest und den SGML-Quellcode der durch das FDP
       betreuten Dokumente versteht,

     * wie man selbst A:nderungen an Dokumenten vornehmen kann und

     * wie man A:nderungen zur Begutachtung durch das FDP einreichen kann.

1.1. Die FreeBSD-Dokumentationsreihe

   Das FDP umfasst vier verschiedene Kategorien:

   Manualpages

           Die englischen Manualpages wurden nicht vom FDP geschrieben, da
           sie ein Teil des Basissystems sind. Jedoch ko:nnen bzw. wurden
           bereits Teile von existierenden Manualpages umformuliert, um sie
           versta:ndlicher zu machen oder um Fehler zu beheben.

           Fu:r die U:bersetzung der Manualpages des Systems in die
           verschiedenen Sprachen sind die einzelnen U:bersetzergruppen
           verantwortlich. Alle dabei entstandenen U:bersetzungen geho:ren
           zum FDP.

   Die FAQ

           Das Ziel der FAQ ist es, Fragen, die auf den verschiedenen
           Mailinglisten und in Newsgruppen regelma:ssig diskutiert werden,
           nach einem einfachen Frage- und Antwort-Muster zu behandeln. Das
           schliesst nicht aus, das auf bestimmte Fragen ausfu:hrlich und
           umfassend eingegangen wird.

   Das Handbuch

           Das Ziel des Handbuches ist es, die umfassende Quelle und Referenz
           im Netz fu:r FreeBSD-Benutzer zu sein.

   Die Webseite

           Die Webseite http://www.FreeBSD.org und ihre vielen Spiegel auf
           der ganzen Welt vertreten das FreeBSD-Projekt im WWW. Fu:r viele
           Menschen ist sie der erste Kontakt mit FreeBSD.

   Die Quellen fu:r die FreeBSD-Website, das FreeBSD Handbuch sowie die
   FreeBSD FAQ werden im doc/ Subversion-Repository von FreeBSD verwaltet,
   das Sie u:ber https://svn.FreeBSD.org/doc/ erreichen ko:nnen.

   Manualpages werden im src/ Subversion-Repository von FreeBSD verwaltet,
   das Sie u:ber https://svn.FreeBSD.org/base/ erreichen ko:nnen.

   Das bedeutet, dass alle A:nderungen an den Dateien fu:r jeden verfu:gbar
   sind und sich jeder mit svn eine lokale Kopie der Dokumentation anlegen
   kann.

   Parallel zum FDP haben viele Menschen Anleitungen geschrieben und
   Webseiten mit Bezug zu FreeBSD erstellt. Einige davon werden im
   Subversion-Archiv verwaltet, sofern der Autor dem zugestimmt hat. In
   anderen Fa:llen hat sich der Autor entschlossen, seine Dokumentation
   ausserhalb des zentralen FreeBSD-Archivs zu verwalten. Das FDP bemu:ht
   sich, so viele Verweise wie mo:glich auf solche Quellen bereitzustellen.

1.2. Bevor es losgeht

   Zum Versta:ndnis der folgenden Kapitel sollte folgendes bereits bekannt
   sein:

     * Wie eine aktuelle lokale Kopie des FreeBSD Subversion-Repository mit
       Hilfe von svn angelegt und gepflegt werden kann.

     * Wie neue Programme mit Hilfe des FreeBSD-Portsystems oder mittels
       pkg_add(1) heruntergeladen und installiert werden.

1.3. Der Schnellstart

   Falls man einfach loslegen mo:chte und sich sicher genug fu:hlt, um alles
   weitere erst bei Bedarf nachzusehen, kann man einfach den folgenden
   Anweisungen folgen:

    1. Zuerst muss der Metaport textproc/docproj auf dem betreffenden
       Arbeitsrechner installiert werden.

 # cd /usr/ports/textproc/docproj
 # make JADETEX=no install

    2. Laden Sie mit svn eine lokale Kopie des FreeBSD-doc-Verzeichnisbaumes
       herunter.

       Selbst wenn Sie nur u:ber eine geringe Bandbreite oder wenig freien
       Plattenplatz verfu:gen, mu:ssen Sie mindestens die Verzeichnisse
       head/share sowie head/language/share auschecken, um an der
       Dokumentation arbeiten zu ko:nnen. Dazu ein Beispiel:

 % mkdir -p head/share
 % mkdir -p head/en_US.ISO8859-1/share
 % svn checkout https://svn0.us-
 east.FreeBSD.org/doc/head/share head/share
 % svn checkout https://svn0.us-
 east.FreeBSD.org/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share

       Fu:r den Fall, dass ausreichend Platz auf der Festplatte vorhanden
       ist, kann auch eine vollsta:ndige Arbeitskopie des gesamten
       Subversion-Baumes anlegt werden.

 % svn checkout https://svn0.us-
 east.FreeBSD.org/doc/head head

  Anmerkung:

       svn0.us-east.FreeBSD.org ist ein o:ffentlicher Server. Wa:hlen Sie
       einen Mirror in Ihrer Na:he und u:berpru:fen Sie das Serverzertifikat
       auf der Seite Subversion mirror sites.

    3. Sollte geplant sein, ein existierendes Buch oder einen existierenden
       Artikel zu a:ndern, muss natu:rlich noch zusa:tzlich das betreffende
       Verzeichnis aus dem CVS-Archiv geholt werden. Soll hingegen ein neues
       Buch oder ein neuer Artikel geschrieben werden, empfiehlt es sich, auf
       bestehende Bu:cher und Artikel zuru:ckzugreifen und diese als Vorlage
       zu nutzen.

       Ein Artikel u:ber die Konfiguration eines VPNs zwischen FreeBSD und
       Windows 2000 kann wie folgt erstellt werden:

         1. Zuerst wird das Verzeichnis articles aus dem FreeBSD-CVS-Archiv
            lokal angelegt:

 % svn checkout https://svn0.us-
 east.FreeBSD.org/doc/head/en_US.ISO8859-1/articles

         2. Anschliessend kopiert man einen bereits existierenden Artikel und
            nutzt ihn als Vorlage. In diesem Beispiel soll der neue Artikel
            im Verzeichnis vpn-w2k liegen:

 % cd head/en_US.ISO8859-1/articles
 % svn export committers-guide vpn-w2k

       Bereits existierende Dokumente, die gea:ndert werden sollen, ko:nnen
       direkt aus dem CVS-Archiv geholt werden. Das folgende Beispiel zeigt
       das fu:r die FAQ aus dem Verzeichnis head/en_US.ISO8859-1/books/faq:

 % svn checkout https://svn0.us-
 east.FreeBSD.org/doc/head/en_US.ISO8859-1/books/faq

    4. Jetzt ko:nnen die .xml Dateien mit einem beliebigen Texteditor
       bearbeitet werden.

    5. Danach ist make mit dem Ziel lint aufzurufen, um das gesamte Dokument
       auf Auszeichnungsfehler hin zu untersuchen, ohne dass zeitaufwa:ndige
       Transformationen vorgenommen werden.

 % make lint

       Soll anschliessend das Zieldokument erstellt werden, kann mit Hilfe
       der Variable FORMATS bestimmt werden, welche Ausgabeformate erzeugt
       werden sollen. Unterstu:tzt werden momentan html, html-split, txt, ps,
       pdf und rtf. Die aktuelle Liste der unterstu:tzten Formate befindet
       sich am Anfang der Datei head/share/mk/doc.docbook.mk. Bei der
       Verwendung dieser Variable ist es wichtig, darauf zu achten, dass die
       Angabe der gewu:nschten Formate in Anfu:hrungszeichen eingeschlossen
       wird, sofern mehr als nur ein Format gleichzeitig erstellt werden
       soll.

       Wenn das Dokument beispielsweise nach HTML konvertiert werden soll,
       kann dies so vorgenommen werden:

 % make FORMATS=html

       Soll es hingegen in den Formaten html und txt erzeugt werden, kann man
       entweder make(1) zweimal hintereinander aufrufen:

 % make FORMATS=html
 % make FORMATS=txt

       oder beide Formate mit einem Aufruf von make(1) erzeugen:

 % make FORMATS="html txt"

    6. Zum Schluss mu:ssen die A:nderungen an das FDP mittels send-pr(1)
       eingesandt werden.

                            Kapitel 2. Die Werkzeuge

   Inhaltsverzeichnis

   2.1. Notwendige Werkzeuge

   2.2. Optionale Werkzeuge

   Innerhalb des FDPs werden verschiedene Programme fu:r die Verwaltung der
   FreeBSD-Dokumentation, ihrer Transformation in verschiede Formate und
   weitere Aufgaben eingesetzt. Wer an der FreeBSD-Dokumentation mitarbeiten
   mo:chte, wird diese Programme beno:tigen.

   Doch dies ist kein Grund zur Angst, da alle notwendigen Programme als
   FreeBSD-Ports und fertige Pakete vorhanden sind, wodurch sich die
   Installation drastisch vereinfacht.

   Allerdings mu:ssen diese Programme installiert werden, bevor alle
   Beispiele der folgenden Kapitel ausprobiert werden ko:nnen.

  Wenn es mo:glich ist, sollte der Port textproc/docproj verwendet werden:

   Durch die Installation des Ports textproc/docproj kann die Installation
   vereinfacht und eine Menge Zeit gespart werden. Bei diesem Port handelt es
   sich um einen Metaport, der selbst keine Programme oder a:hnliches
   installiert. Stattdessen entha:lt er eine Vielzahl von Abha:ngigkeiten zu
   anderen Ports und setzt deren korrekte Installation voraus. Durch seine
   Installation sollten automatisch alle Pakete, die in diesem Kapitel
   genannt werden, auf den Rechner geladen und dort installiert werden.

   Ein nur unter bestimmten Umsta:nden beno:tigter Port ist das
   JadeTeX-Makro-Paket, das seinerseits eine TeX-Installation voraussetzt.
   TeX ist ein ziemlich grosses Programmpaket und sollte nur installiert
   werden, sofern Zieldokumente im PostScript- oder PDF-Format generiert
   werden sollen.

   Um den Platz und die Zeit fu:r die Installation von JadeTeX und TeX zu
   sparen, muss bei der Installation angeben werden, ob JadeTeX (und damit
   auch TeX) installiert werden soll oder nicht.

   Daher sollte der docproj-Port entweder mit

 # make JADETEX=yes install

   oder mit

 # make JADETEX=no install

   installiert werden, je nachdem was gewu:nscht wird. Alternativ ko:nnen Sie
   auch direkt die Ports textproc/docproj-jadetex oder
   textproc/docproj-nojadetex installieren. Die Variable JADETEX wird von
   diesen Ports automatisch entsprechend gesetzt. Ohne JadeTeX ko:nnen Sie
   nur die Formate HTML und ASCII erzeugen. Die Formate PostScript und PDF
   erfordern TeX.

2.1. Notwendige Werkzeuge

  2.1.1. Software

   Die folgenden Programme sind notwendig, um sinnvoll an der
   FreeBSD-Dokumentation arbeiten und diese in andere Formate wie HTML,
   reinen Text und RTF umwandeln zu ko:nnen. Sie mu:ssen diese aber nicht
   separat installieren, da alle Programme automatisch durch den Metaport
   textproc/docproj installiert werden.

   Jade (textproc/jade)

           Eine DSSSL-Implementierung. Sie wird gebraucht, um Dokumente in
           andere Formate wie HTML und TeX zu u:bersetzen.

   Tidy (www/tidy)

           Ein Formatierer, mit dem man Teile der automatisch generierten
           HTML-Dateien neuformatieren kann, um ihre Lesbarkeit zu erho:hen.

   Links (www/links)

           Ein Textbrowser, der HTML-Dateien in einfache Textdateien
           umwandeln kann.

   peps (graphics/peps)

           Einige der Dokumente enthalten Grafiken, die nur im EPS-Format
           vorliegen. Damit diese von dem meisten Webbrowsern angezeigt
           werden ko:nnen, mu:ssen sie nach PNG konvertiert werden.

  2.1.2. Die DTDs und die Entita:ten

   Das FDP benutzt verschiedene DTDs und Entita:tensa:tze, die installiert
   sein mu:ssen, bevor mit der Arbeit an einem beliebigen Dokument begonnen
   werden kann.

   HTML DTD (textproc/html)

           HTML ist die bevorzugte Auszeichnungssprache des World Wide Web
           und wird durchga:ngig fu:r die FreeBSD-Webseite genutzt.

   DocBook DTD (textproc/docbook)

           DocBook ist als Auszeichnungssprache fu:r technische
           Dokumentationen entwickelt worden. Die gesamte
           FreeBSD-Dokumentation wird mittels DocBook erstellt.

   ISO 8879-Entita:ten (textproc/iso8879)

           19 der ISO 8879:1986-Zeichensa:tze, die von vielen DTDs beno:tigt
           werden. Darin enthalten sind mathematische Symbole, zusa:tzliche
           Zeichen, die fu:r auf dem lateinischen beruhende Alphabete
           beno:tigt werden sowie griechische Zeichen.

  2.1.3. Die Stilvorlagen

   Die Stilvorlagen werden wa:hrend der Transformation und der Formatierung
   von Dokumenten, beispielsweise fu:r die Bildschirmdarstellung oder den
   Druck, benutzt.

   Modular DocBook Stylesheets (textproc/dsssl-docbook-modular)

           Die Modular DocBook Stylesheets werden beno:tigt, wenn mittels
           DocBook erstellte Dokumente in Formate wie HTML oder RTF
           konvertiert werden sollen.

2.2. Optionale Werkzeuge

   Die in diesem Kapitel genannten Programme mu:ssen nicht unbedingt
   installiert werden. Allerdings ko:nnen sie die Arbeit an der Dokumentation
   erleichtern und die Anzahl an mo:glichen Ausgabeformaten erho:hen.

  2.2.1. Software

   JadeTeX und teTeX (print/jadetex und print/teTeX)

           Jade und teTeX werden eingesetzt, um DocBook-Dokumente nach DVI,
           Postscript und PDF zu konvertieren. Hierfu:r mu:ssen die JadeTeX
           Makros installiert sein.

           Ist es nicht geplant, die Dokumente in einem dieser Formate zu
           erzeugen, wenn also HTML, Text und RTF ausreichend sind, brauchen
           JadeTeX und teTeX nicht installiert zu werden. Da die Installation
           von teTeX insgesamt 30 MB beno:tigt, kann so Zeit und Plattenplatz
           gespart werden.

  Wichtig:

           Wird sich fu:r die Installation von JadeTeX und teTeX entschieden,
           muss teTeX anschliessend noch eingerichtet werden. Die Datei
           print/jadetex/pkg-message entha:lt detailierte Angaben zu den
           dafu:r notwendigen Schritten.

   Emacs oder XEmacs (editors/emacs oder editors/xemacs)

           Beide Texteditoren haben einen speziellen Modus zur Bearbeitung
           von SGML-Dokumenten entsprechend den Vorgaben einer SGML-DTD.
           Zusa:tzlich bieten sie Funktionen an, mit denen sich der
           Tippaufwand reduzieren und Fehlerwahrscheinlichkeit senken la:sst.

           Natu:rlich muss nicht mit einem dieser Texteditoren gearbeitet
           werden; jeder andere Editor kann dafu:r genausogut genutzt werden,
           doch vielleicht wird die Arbeit durch sie als effektiver empfunden
           werden.

   Sofern Sie Vorschla:ge haben, welche andere Software fu:r die Verarbeitung
   oder Bearbeitung von SGML-Dokumenten in diese Liste mitaufgenommen werden
   sollte, senden Sie diese bitte an Documentation Engineering Team
   <doceng@FreeBSD.org>.

                            Kapitel 3. Die XML-Fibel

   Inhaltsverzeichnis

   3.1. U:berblick

   3.2. Von Elementen, Tags und Attributen

   3.3. Die DOCTYPE-Deklaration

   3.4. Die Ru:ckkehr zu SGML

   3.5. Kommentare

   3.6. Entita:ten

   3.7. Dateien mit Entita:ten einbinden

   3.8. Markierte Bereiche

   3.9. Schlussbemerkung

   Die Mehrzahl der Dokumente des FDPs sind in XML geschrieben. Ziel dieses
   Kapitels ist es, genau zu erkla:ren, was das bedeutet und wie man die
   XML-Quellen liest und versteht. Ebenso werden die in den Quellen genutzten
   Kniffe erkla:rt, auf die man beim Lesen der Dokumente stossen wird.

   Teile dieses Kapitels basieren auf Mark Galassis "Get Going With DocBook".

3.1. U:berblick

   In den guten alten Zeiten war der Umgang mit "elektronischem" Text
   einfach. Man musste lediglich wissen, welcher Zeichensatz (ASCII, EBCDIC
   oder ein anderer) vorlag. Text war einfach Text und sah so aus, wie man
   ihn sah. Keine Extras, keine Formatierungen und kein sonstiger
   Schnickschnack.

   Fu:r viele Zwecke war dies allerdings nicht ausreichend. Von einem
   maschinenlesbaren Text wird erwartet, dass er auch von Maschinen gelesen
   und intelligent weiterverarbeitet werden kann. Einzelne Stellen sollen
   hervorgehoben werden, andere sollen in ein Glossar aufgenommen werden oder
   auf andere Textstellen verweisen. Dateinamen wiederum sollen in einer
   "schreibmaschinena:hnlichen" Schrift auf dem Bildschirm dargestellt
   werden, der Ausdruck soll jedoch in "Schra:gschrift" oder in einer
   beliebigen anderen Darstellungsform erfolgen.

   Anfa:nglich gab es die Hoffnung, dass die Ku:nstliche Intelligenz (KI)
   helfen wu:rde, dieses Ziel zu erreichen. Computer sollte den Text lesen
   und dazu in der Lage sein, selbststa:ndig wichtige Formulierungen,
   Dateinamen, Benutzereingaben oder Beispiele zu erkennen. Leider verlief
   die Entwicklung in diesem Bereich nicht wie gewu:nscht und Computer
   beno:tigen nach wie vor etwas Unterstu:tzung, bevor sie Texte vernu:nftig
   verarbeiten ko:nnen.

   Genauer gesagt, man muss ihnen sagen, was was ist. Sehen wir uns folgende
   Zeilen an:

     Lo:schen Sie /tmp/foo mittels rm(1).

 % rm /tmp/foo

   Es fa:llt uns leicht, zu erkennen, was ein Dateiname, ein einzugebender
   Befehl oder ein Verweis auf eine Hilfeseite ist. Das kann ein Computer,
   der einen Text verarbeitet, nicht. Aus diesem Grund ist es notwendig,
   Texte mit weiteren Informationen "auszuzeichnen".

   Der Begriff "Auszeichnung[1]" bedeutet, dass sich der Wert eines Textes
   erho:ht, aber auch seine Kosten. Durch Auszeichnungen wird einem Dokument
   zusa:tzlicher Text hinzugefu:gt, der aber von dem eigentlichen
   Dokumenteninhalt auf eine bestimmte Art und Weise unterschieden werden
   kann, so dass Programme die Auszeichnung erkennen ko:nnen und mittels
   dieser Informationen wa:hrend der Verarbeitung in der Lage sind,
   Entscheidungen zu treffen. Texteditoren ko:nnen diese
   Auszeichnungselemente vor dem Benutzer verbergen, um zu vermeiden, dass er
   durch sie abgelenkt wird.

   Die durch die Auszeichnungselemente im Textdokument zusa:tzlich abgelegten
   Informationen erho:hen den Wert des Dokuments. Allerdings muss diese
   Arbeit in den meisten Fa:llen von einem Menschen getan werden - wa:ren
   Maschinen dazu fa:hig, wa:ren zusa:tzliche Auszeichnungselemente unno:tig.
   Der damit verbundene Aufwand erho:ht die Kosten, die durch die Erstellung
   des Dokuments entstehen.

   Das etwas weiter oben gegebene Beispiel sieht im Quelltext so aus:

 <para>Lo:schen Sie <filename>/tmp/foo</filename> mittels &man.rm.1;.</para>

 <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>

   Die Auszeichnungselemente sind deutlich vom eigentlichen Inhalt zu
   unterscheiden.

   Die Einfu:hrung von Auszeichnungselementen setzt voraus, dass festgelegt
   wird, welche Bedeutung einzelne Elemente haben und wie diese interpretiert
   werden. Sie brauchen daher eine Auszeichnungssprache, der Sie folgen, wenn
   Sie eigene Dokumente verfassen.

   Natu:rlich kann es keine universelle Auszeichnungssprache geben und eine
   einzige mag nicht ausreichend fu:r alle mo:glichen Anwendungsfa:lle sein.
   Eine Sprache fu:r technische Dokumente wird sich wahrscheinlich stark von
   einer fu:r Kochrezepte unterscheiden. Die universelle Lo:sung ist eine
   Basissprache, mit deren Hilfe weitere Sprachen entwickelt werden ko:nnen -
   eine Meta-Auszeichnungssprache also.

   Genau diese Anforderung wird von der Standard Generalized Markup Language
   (SGML) erfu:llt. Mit ihrer Hilfe wurden viele andere Auszeichnungssprachen
   wie beispielsweise HTML und DocBook, welche beide von FDP genutzt werden,
   entwickelt.

   Die eigentliche Sprachdefinition erfolgt in einer
   Dokumenten-Typ-Definition (DTD). Innerhalb dieser DTD werden die Namen der
   einzelnen Elemente, deren mo:gliche Reihenfolge und Verschachtelung sowie
   weitere Informationen festgelegt.

   Eine DTD ist eine vollsta:ndige Definition aller mo:glichen
   Sprachelemente, ihrer Reihenfolge[2], optionaler Elemente und so weiter
   und so weiter. Dank dieser recht formalen Festlegung ist es mo:glich,
   SGML-Parser zu entwickeln, die sowohl ein Dokument als auch seine DTD
   einlesen und anhand dieser DTD pru:fen ko:nnen, ob das Dokument allen
   Anforderungen der DTD entspricht. Dieser Vorgang wird allgemein als
   Validierung des Dokuments bezeichnet.

  Anmerkung:

   Das Validieren eines SGML-Dokuments gegen eine DTD u:berpru:ft lediglich
   die korrekte Syntax des Dokuments, dass heisst, ob nur gu:ltige
   Auszeichnungselemente verwendet wurden und ihre Reihenfolge stimmt. Dabei
   wird nicht gepru:ft, ob die Elemente der DTD sinngema:ss verwandt wurden.
   Sollten beispielsweise alle Dateinamen als Funktionsnamen ausgezeichnet
   worden sein, so wu:rde der Parser keinen Fehler signalisieren. Formaler
   ausgedru:ckt: Der Parser pru:ft die Syntax, aber nicht die Semantik.

   Es ist anzunehmen, dass, wenn man selber vor hat Dokumentation fu:r das
   FDP zu schreiben, der gro:sste Teil davon mit Hilfe von HTML oder DocBook
   geschrieben werden wird. Aus diesem Grunde wird an dieser Stelle nicht
   erkla:rt, wie eine DTD entwickelt wird.

3.2. Von Elementen, Tags und Attributen

   Alle in SGML geschriebenen DTDs haben bestimmte gemeinsame Eigenschaften.
   Das ist nicht verwunderlich, da sich die hinter SGML stehende Idee
   unweigerlich bemerkbar macht. Zwei der markantesten Merkmale dieser Idee
   sind die Begriffe Inhalt und Element.

   Von einem Dokument, unabha:ngig, ob es sich um eine einzelne Webseite oder
   ein langes Buch handelt, wird angenommen, dass es einen wie auch immer
   gearteten Inhalt hat. Dieser la:sst sich selbst wiederum in Teilelemente
   aufspalten, die ebenso zerlegbar sind. Durch die Aufnahme von
   Auszeichnungselementen in einen Text, werden diese einzelnen Elemente
   eindeutig benannt und voneinander abgegrenzt.

   Nimmt man zum Beispiel ein typisches Buch, so kann man es auf der obersten
   Ebene als ein Ganzes, als ein Element betrachten. Dieses "Buch"-Element
   entha:lt nun Kapitel, die wiederum selbst als Elemente bezeichnet werden
   ko:nnen. Jedes einzelne Kapitel entha:lt weitere Elemente. So gibt es
   beispielsweise Absa:tze, Zitate und Fussnoten. Jeder Absatz kann wiederum
   selbst Elemente enthalten, die helfen, den Absatzinhalt als direkte Rede
   oder als Namen eines der Protagonisten einer Geschichte zu identifizieren.

   Wenn man mo:chte, kann man sich das als "Unterteilung"[3] des Inhalts
   vorstellen. Auf der obersten Ebene gibt es ein Element: das Buch selbst.
   Schaut man ein wenig tiefer, findet man weitere Teilelemente: die
   einzelnen Kapitel. Diese sind wiederum unterteilt in Absa:tze, Fussnoten,
   Namen und so weiter und so weiter.

   Anzumerken ist an dieser Stelle, dass das eben gesagte ohne weiteres auf
   jeden Inhaltstyp angewandt werden kann, auch ohne dass von SGML die Rede
   ist. Man ko:nnte beispielsweise einfach verschiedene Stifte nehmen und
   einen Ausdruck dieser Fibel vor sich hinlegen und dann mit verschiedenen
   Farben die einzelnen Abschnitte des Buchinhalts markieren.

   Leider gibt es keinen elektronischen Stift, um das zu tun. Deshalb muss
   ein anderer Weg gewa:hlt werden, um zu bestimmen, zu welchem Element die
   einzelnen Inhalte geho:ren. In SGML-basierten Auszeichnungssprachen wie
   HTML und DocBook werden dafu:r so genannte Tags eingesetzt.

   Mit einem solchen Tag wird eindeutig festgelegt, wo ein bestimmtes Element
   beginnt und wo es endet. Allerdings geho:rt der Tag selber nicht zum
   Element. Er legt lediglich die Grenzen des Elements fest. Da jede DTD mit
   dem Ziel entwickelt wurde, einen speziellen Inhaltstyp auszuzeichnen, wird
   jede DTD verschiedene Elemente kennen, die daher natu:rlich auch
   unterschiedlich benannt sein werden.

   Der Starttag fu:r ein imagina:res Element mit dem Namen elementname ist
   <elementname>. Sein Gegenstu:ck, der schliessende Endtag, ist
   </elementname>.

   Beispiel 3.1. Verwendung eines Elements (Start- und Endtag)

   HTML kennt das Element p, um festzulegen, dass ein bestimmter abgegrenzter
   Bereich einen Absatz darstellt. Dieses Element hat sowohl einen Start- als
   auch einen Endtag.

 <p>Das ist ein Absatz. Er beginnt mit Starttag
   fu:r das Element 'p' und endet mit dem Endtag fu:r
   das Element 'p'.</p>

 <p>Das ist ein etwas ku:rzerer Absatz.</p>

   Elemente mu:ssen nicht notwendigerweise einen Endtag haben. Ebenso ist es
   nicht notwendig, dass Elemente einen Inhalt haben. Beispielsweise kann in
   HTML-Dokumenten mittels eines speziellen Elements festgelegt werden, dass
   eine horizontale Linie an einer bestimmten Stelle erscheinen soll. Da
   dieses Element offensichtlich keinen Inhalt hat, wird auch kein Endtag
   beno:tigt.

   Beispiel 3.2. Verwendung eines Elements (nur Starttag)

   In HTML kann man mit dem Element hr festlegen, dass an einer bestimmten
   Stelle eine horizontale Linie angezeigt werden soll. Da dieses Element
   keinen Inhalt umschliesst, hat es nur einen Starttag.

 <p>Das ist ein Abschnitt.</p>

 <hr>

 <p>Das ist ein weiterer Absatz. Eine horizontale Linie
   trennt ihn vom vorherigen Absatz.</p>

   Elemente ko:nnen andere Elemente enthalten. Im anfangs erwa:hnten Buch
   enthielt das Buch-Element alle Kapitel-Elemente, die wiederum alle
   Absatz-Elemente enthielten und so fort.

   Beispiel 3.3. Verschachtelte Elemente: em

 <p>Das ist ein einfacher <em>Abschnitt</em>, in dem
   einige <em>Worte</em> <em>hervorgehoben</em> wurden.

   Welche Elemente andere Elemente enthalten ko:nnen und welche das sind,
   wird innerhalb der DTD eines Dokuments festgelegt.

  Wichtig:

   Viele Leute sind oft verwirrt, wenn es um die richtige Benutzung der
   Begriffe Tag und Element geht. Im Ergebnis werden sie oft so genutzt, als
   wa:ren sie austauschbar. Allerdings sind sie das nicht.

   Ein Element ist ein konzeptioneller Teil eines Dokuments und hat einen
   festgelegten Anfang und ein festgelegtes Ende. Ein Tag hingegen markiert
   die Stelle, an der ein Element beginnt und endet.

   Wenn in diesem Dokument vom "Tag p" gesprochen wird, ist damit der Text
   gemeint, der aus den drei Zeichen <, p und > besteht. Wird hingegen von
   dem "Element p" gesprochen, ist damit das gesamte Element gemeint.

   Diese Unterscheidung ist sicherlich subtil. Trotzdem sollte man sie sich
   vergegenwa:rtigen.

   Elemente ko:nnen selber Attribute haben, die aus einem Namen und einem
   Wert bestehen. Die Attribute haben die Aufgabe, dem Element zusa:tzliche
   Informationen hinzuzufu:gen. Denkbar sind hier Festlegungen u:ber die
   Darstellung, Bezeichner, u:ber die das Element eindeutig identifiziert
   werden kann, oder beliebige andere Informationen.

   Elementattribute werden in den Starttag eingefu:gt und haben die Form
   Attributename="Wert".

   Bei einigen HTML-Versionen kennt das Element p das Attribut align, mit
   dessen Hilfe die Textausrichtung eines Absatzes bestimmt werden kann.

   align akzeptiert einen von vier vorgegebenen Werten: left, center, right
   und justify. Ist align nicht angegeben, wird vom Standardwert left
   ausgegangen.

   Beispiel 3.4. Elemente mit Attributen nutzen

 <p align="left">Die Verwendung des align-Attributs
   fu:r diesen Absatz ist u:berflu:ssig, da left
   der Standardwert ist.</p>

 <p align="center">Dieser Absatz wird hoffentlich mittig dargestellt.</p>

   Einige Attribute akzeptieren nur bestimmte Werte, wie beispielsweise left
   oder justify. Andere akzeptieren jeden beliebigen Wert. Entha:lt
   Attributwert doppelte Anfu:hrungszeichen ("), wird der Wert in einfachen
   Anfu:hrungszeichen eingeschlossen.

   Beispiel 3.5. Attribute mit einfachen Anfu:hrungszeichen

 <p align='right'>Ich stehe rechts!</p>

   Manchmal ko:nnen die Anfu:hrungszeichen um den Attributwert weggelassen
   werden. Allerdings sind die Regeln, die festlegen wann dies zula:ssig ist,
   sehr spitzfindig. Am besten schliessen Sie Attributwerte immer in
   Anfu:hrungszeichen ein.

   Die Informationen u:ber Attribute, Elemente und Tags sind in
   SGML-Katalogen abgelegt und werden von den verschiedenen Werkzeugen des
   Dokumentationsprojektes genutzt, um die geschriebenen Dokumente zu
   validieren. Die Programme die durch textproc/docproj installiert werden,
   bringen ihre eigenen Katalogvarianten mit, zudem pflegt das FDP seine
   eigenen Kataloge. Beide Katalogarten mu:ssen von allen Programmen gefunden
   werden ko:nnen.

  3.2.1. Was dafu:r getan werden muss;...

   Damit die Beispiele dieser Fibel ausgefu:hrt werden ko:nnen, ist es
   notwendig, dass einige Programme auf dem Rechner installiert sind und das
   eine Umgebungsvariable korrekt gesetzt wird.

    1. Der erste Schritt ist die Installation des Ports textproc/docproj
       u:ber das FreeBSD-Portsystem. textproc/docproj ist ein Metaport, der
       alle vom FDP beno:tigten Programme und Daten aus dem Netz laden und
       installieren sollte.

    2. Anschliessend muss in den Shellkonfigurationsdateien die Variable
       SGML_CATALOG_FILES [4] gesetzt werden.

       Beispiel 3.6. .profile, fu:r sh(1) und bash(1) Benutzer

 SGML_ROOT=/usr/local/share/xml
 SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
 SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=/usr/doc/share/xml/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES
 export SGML_CATALOG_FILES

       Beispiel 3.7. .cshrc, fu:r csh(1)- und tcsh(1)-Benutzer

 setenv SGML_ROOT /usr/local/share/xml
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES /usr/doc/share/xml/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES /usr/doc/de_DE.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES

       Damit die A:nderungen wirksam werden, meldet man sich ab und
       anschliessend wieder an - oder man fu:hrt die obigen Anweisungen
       direkt in der Shell aus und setzt so die beno:tigten
       Umgebungsvariablen.

    1. Nun sollte man eine Datei beispiel.xml anlegen, die den folgenden Text
       entha:lt:

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

 <html>
   <head>
     <title>Eine Beispieldatei in HTML</title>
   </head>

   <body>
     <p>Das ist ein Absatz mit etwas Text.</p>

     <p>Das ist ein Absatz mit anderem Text.</p>

     <p align="right">Dieser Absatz wird rechtsbu:ndig
       ausgerichtet.</p>
   </body>
 </html>

    2. Nachdem die Datei abgespeichert wurde, kann sie mit Hilfe eines
       SGML-Parsers validiert werden.

       Bestandteil von textproc/docproj ist onsgmls - ein validierender
       Parser. onsgmls liest ein Dokument entsprechend einer SGML-DTD ein und
       gibt anschliessend ein Element-Structure-Information-Set (ESIS) aus.
       Allerdings ist das an dieser Stelle nicht weiter wichtig.

       Wird onsgmls mit der Option -s aufgerufen, werden nur Fehlermeldungen
       ausgegeben. Dadurch kann leicht gepru:ft werden, ob ein Dokument
       gu:ltig ist oder nicht.

       So pru:ft man mit onsgmls, ob die neuangelegte Beispieldatei gu:ltig
       ist:

 % onsgmls -s beispiel.xml

       Sofern das Beispiel korrekt abgetippt wurde, wird sich onsgmls ohne
       jegliche Ausgabe beenden. Das bedeutet, dass das Dokument erfolgreich
       validiert werden konnte und somit gu:ltig ist.

    3. Jetzt sollten die Tags title und /title aus dem Dokument gelo:scht und
       das Dokument erneut validiert werden:

 % onsgmls -s beispiel.xml
 onsgmls:beispiel.xml:5:4:E: character data is not allowed here
 onsgmls:beispiel.xml:6:8:E: end tag for "HEAD" which is not finished

       Die Fehlermeldungen, die von onsgmls ausgegeben werden, sind in durch
       Doppelpunkte getrennte Spalten unterteilt.

       Spalte                            Bedeutung                            
       1       Der Name des Programms, das den Fehler meldet. Hier wird immer 
               onsgmls stehen.                                                
       2       Der Name der fehlerhaften Datei.                               
       3       Die Zeilennummer des Fehlers.                                  
       4       Die Spaltenummer des Fehlers.                                  
               Ein einbuchstabiger Code, der u:ber die Art des Fehlers        
               informiert. I steht fu:r eine informelle Meldung, W fu:r eine  
       5       Warnung und E fu:r Fehler[a] und X fu:r einen Querverweis. Bei 
               den oben stehenden Ausgaben handelt es sich also um            
               Fehlermeldungen.                                               
       6       Die Meldung.                                                   
       [a] Nicht immer besteht eine Meldung aus fu:nf Spalten. Die Ausgabe
       von onsgmls -sv ist beispielsweise onsgmls:I: SP version "1.3"
       (natu:rlich abha:ngig von der Version). Wie man sehen kann, handelt es
       sich hier um eine informelle Meldung.

       Durch das Weglassen des Tags title sind zwei unterschiedliche Fehler
       entstanden.

       Der erste Fehler besagt, dass Inhalt (in diesem Falle Zeichen anstatt
       eines Starttags) an einer Stelle gefunden wurde, an der der Parser
       etwas anderes erwartet hat. Genauer gesagt wurde der Starttag eines
       Elements erwartet, das innerhalb von head auftreten kann.

       Der zweite Fehler wurde dadurch verursacht, dass das Element head ein
       Element title enthalten muss und onsgmls nicht beru:cksichtigt, dass
       dieser Fehler auf dem vorhergehenden beruht. Es wird lediglich
       festgestellt, dass der Endtag von head auftritt, obwohl nicht alle
       notwendigen Elemente vorhanden sind.

    4. Zum Schluss sollte der Tag title wieder in die Beispieldatei
       eingefu:gt werden.

3.3. Die DOCTYPE-Deklaration

   Am Anfang jedes Dokuments muss der Name der dem Dokument zugrundeliegenden
   DTD angegeben werden. Mit Hilfe dieser Information ko:nnen SGML-Parser die
   verwendete DTD feststellen und pru:fen, ob das Dokument zu ihr konform
   ist.

   U:blicherweise steht diese Information in einer Zeile, die als
   DOCTYPE-Deklaration bezeichnet wird.

   Eine Deklaration fu:r ein HTML-Dokument, das nach den Vorgaben der DTD
   fu:r HTML 4.0 geschrieben wurde, sieht so aus:

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">

   und besteht aus verschiedenen Teilen.

   <!

           Die Zeichenkette <! dient hier als Indikator, dass es sich bei
           diesem Ausdruck um eine SGML-Deklaration handelt und diese Zeile
           den Dokumententyp festlegt.

   DOCTYPE

           Zeigt an, dass dies die SGML-Deklaration fu:r den Dokumententyp
           ist.

   html

           Nennt das erste Element, das im Dokument auftaucht.

   PUBLIC "-//W3C//DTD HTML 4.0//EN"

           Nennt den Formalen O:ffentlichen Bezeichner [5] der DTD des
           Dokuments. Diese Information wird von SGML-Parsern ausgewertet, um
           die von dem Dokument referenzierte DTD zu bestimmen.

           Das Schlu:sselwort PUBLIC geho:rt nicht zum o:ffentlichen
           Bezeichner, sondern legt fest, wie ein SGML-Parser die DTD finden
           kann. Alternative Wege eine DTD zu referenzieren werden spa:ter
           gezeigt.

   >

           Schliesst den mit <! begonnenen Ausdruck ab.

  3.3.1. Formale O:ffentliche Bezeichner

  Anmerkung:

   Dieser Abschnitt braucht nicht unbedingt zu gelesen zu werden. Dennoch ist
   es empfehlenswert, da er nu:tzliche Hintergrundinformationen entha:lt, die
   hilfreich sein ko:nnen, falls der SGML-Prozessor die genutzte DTD nicht
   finden kann.

   Jeder o:ffentliche Bezeichner muss eine bestimmte Syntax haben, die wie
   folgt lautet:

 "Besitzer//Schlu:sselwort Beschreibung//Sprache"

   Besitzer

           Nennt den Besitzer des o:ffentlichen Bezeichners.

           Falls diese Zeichenkette mit "ISO" beginnt, geho:rt der Bezeichner
           dem ISO-Komitee. Der Bezeichner "ISO 8879:1986//ENTITIES Greek
           Symbols//EN" nennt "ISO 8879:1986" als den Besitzer des Satzes von
           Entita:ten fu:r griechische Zeichen. ISO 8879:1986 ist die
           ISO-Bezeichnung fu:r den SGML-Standard.

           Beginnt die Zeichenkette nicht mit "ISO", sieht sie entweder so
           -//Besitzer oder so +//Besitzer aus. Beide Varianten unterscheiden
           sich also nur durch das anfa:ngliche + bzw. -.

           Sofern am Anfang ein - steht, ist der Bezeichner nicht o:ffentlich
           registriert, steht hingegen ein + am Anfang, ist er registriert.

           Im ISO-Standard ISO 9070:1991 wurde festgelegt, wie registrierte
           Namen erzeugt werden ko:nnen. Unter anderem ko:nnen sie von den
           Bezeichnungen von ISO-Publikationen, von ISBN-Nummern oder einer
           Organisationsbezeichnungen entsprechend ISO 6523 abgeleitet
           werden. Antra:ge fu:r neue offiziell registrierte Bezeichner
           werden vom ISO-Komitee an das American National Standards
           Institute (ANSI) weitergeleitet.

           Da das FreeBSD-Projekt seine Bezeichner nicht hat registrieren
           lassen, ist der Besitzer -//FreeBSD. Unter anderem kann man daran
           auch sehen, dass das W3C sich nicht hat registrieren lassen.

   Schlu:sselwort

           Es gibt verschiedene Schlu:sselwo:rter mit denen man die Art der
           gegebenen Informationen beschreiben kann. Einige der u:blichsten
           sind DTD, ELEMENT, ENTITIES und TEXT. DTD wird nur fu:r Dateien
           mit DTDs verwandt, ELEMENT findet fu:r Dateien mit Fragmenten von
           DTDs Verwendung, die nur Deklarationen fu:r Entita:ten und
           Elemente enthalten. TEXT wird fu:r SGML-Inhalte (Texte und Tags)
           verwendet.

   Beschreibung

           Eine frei wa:hlbare Beschreibung des Inhalts der referenzierten
           Datei. Mo:glich sind hier Versionsnummern oder ein kurzer und
           sinnvoller Text, der innerhalb der SGML-Welt eindeutig ist.

   Sprache

           Ein ISO-Code aus zwei Buchstaben, der die fu:r die Datei
           verwendete Sprache nennt. EN steht hier fu:r Englisch, DE fu:r
           Deutsch.

    3.3.1.1. Die catalog-Dateien

   Wenn man die oben beschriebene Syntax fu:r Bezeichner verwendet und ein
   Dokument durch einen SGML-Prozessor schickt, muss dieser die Mo:glichkeit
   haben, den Bezeichner auf eine real existierende Datei abzubilden, die die
   beno:tigte DTD entha:lt.

   Einer der mo:glichen Wege hierfu:r sind Katalogdateien. Eine solche Datei,
   die u:blicherweise catalog heisst, besteht aus einzelnen Zeilen, die
   Bezeichner auf Dateinamen abbilden. Entha:lt ein Katalog beispielsweise
   die Zeile

 PUBLIC "-//W3C//DTD HTML 4.0//EN"             "4.0/strict.dtd"

   kann ein SGML-Prozessor daru:ber feststellen, dass die beno:tigte DTD in
   der Datei strict.dtd im Unterverzeichnis 4.0 des Verzeichnisses des
   Katalogs zu finden ist.

   Ein gutes Beispiel fu:r einen Katalog ist
   /usr/local/share/xml/html/catalog. Diese Datei entha:lt den Katalog fu:r
   alle HTML DTDs, die im Zuge der Installation von textproc/docproj
   installiert wurden.

    3.3.1.2. Die Variable SGML_CATALOG_FILES

   Natu:rlich muss einem SGML-Prozessor noch mitgeteilt werden ko:nnen, wo er
   seine Kataloge finden kann. Viele Programme bieten hierfu:r
   Kommandozeilenoptionen an, u:ber die man einen oder mehrere Kataloge
   angeben kann.

   Zusa:tzlich besteht noch die Mo:glichkeit mit der Umgebungsvariablen
   SGML_CATALOG_FILES auf SGML-Kataloge zu verweisen. Die Eintra:ge von
   SGML_CATALOG_FILES mu:ssen aus den vollsta:ndigen Pfadnamen der Kataloge,
   jeweils durch Komma getrennt, bestehen.

   U:blicherweise werden die folgenden Kataloge u:ber SGML_CATALOG_FILES fu:r
   die Arbeit an den Dokumenten des FDPs eingebunden:

     * /usr/local/share/xml/docbook/4.1/catalog

     * /usr/local/share/xml/html/catalog

     * /usr/local/share/xml/iso8879/catalog

     * /usr/local/share/xml/jade/catalog

   Allerdings sollte das schon geschehen sein.

  3.3.2. Alternativen zu Formalen O:ffentlichen Bezeichnern

   Anstatt mit einem Bezeichner die zum Dokument geho:rende DTD zu
   referenzieren, kann auch explizit auf die Datei der DTD verwiesen werden.

   Die Syntax der DOCTYPE-Deklaration ist in diesem Falle anders:

 <!DOCTYPE html SYSTEM "/pfad/zur/dokumenten.dtd">

   Das Schlu:sselwort SYSTEM legt fest, dass ein SGML-Prozessor die DTD auf
   "systemspezifische" Art und Weise bestimmen soll. Meistens, aber nicht
   immer, wird so auf eine Datei im Dateisystem verwiesen.

   Allerdings sollte man o:ffentliche Bezeichner aus Gru:nden der
   Portabilita:t bevorzugen, da man so nicht eine Kopie der DTD mit dem
   Dokument selber verteilen muss, beziehungsweise da man, wenn man mit
   SYSTEM arbeitet, nicht davon ausgehen kann, dass die beno:tigte DTD auf
   anderen Systemen genau unter dem gleichen Pfad verfu:gbar ist.

3.4. Die Ru:ckkehr zu SGML

   An einer fru:heren Stelle wurde erwa:hnt, dass man SGML nur beno:tigt,
   falls man selbst eine DTD entwickeln mo:chte. Genaugenommen ist das nicht
   100%ig richtig. Einige Teile der SGML-Syntax ko:nnen auch in normalen
   Dokumenten verwendet werden, falls dies gewu:nscht oder notwendig ist.

   In diesem Falle muss dafu:r Sorge getragen werden, dass ein SGML-Prozessor
   feststellen kann, dass ein bestimmter Abschnitt des Inhalts SGML ist, das
   er verarbeiteten muss.

   Solche SGML-Abschnitte werden mittels <! ... > in Dokumenten besonders
   gekennzeichnet. Alles, was sich zwischen diesen Begrenzungen befindet, ist
   SGML, wie es auch in DTDs gefunden werden kann.

   Demnach ist die DOCTYPE-Deklaration ein gutes Beispiel fu:r SGML, das in
   Dokumenten verwendet werden muss...

3.5. Kommentare

   Kommentare sind SGML-Konstrukte, die normalerweise nur in DTDs gu:ltig
   sind. Dennoch ist es, wie in Abschnitt 3.4, "Die Ru:ckkehr zu SGML"
   gezeigt, mo:glich Fragmente mit SGML-Syntax in Dokumenten zu verwenden.

   Zum Abgrenzen von SGML-Kommentaren wird ein doppelter Bindestrich "--"
   verwendet. Mit seinem ersten Auftreten o:ffnet er einen Kommentar, mit
   seinem zweiten schliesst er ihn wieder.

   Beispiel 3.8. Beispiele fu:r Kommentare in SGML

 <!-- Testkommentar -->

 <!-- Text innerhalb eines Kommentars -->

 6lt;!-- Ein anderer Kommentar    -->

 6lt;!-- So ko:nnen mehrzeilige Kommentare
      genutzt werden -->

 <!-- Eine andere Mo:glichkeit fu:r --
   -- mehrzeilige Kommentare.     -->

   Hat man fru:her schon Erfahrungen mit HTML gesammelt, wird man vielleicht
   andere Regeln fu:r den Gebrauch von Kommentaren kennengelernt haben.
   Beispielsweise wird oft angenommen, dass Kommentare mit <!-- begonnen und
   nur mit --> beendet werden.

   Dies ist nicht der Fall. Viele Webbrowser haben fehlerhafte HTML-Parser,
   die dies akzeptieren. Die SGML-Parser, die vom FDP verwendet werden,
   halten sich strenger an die SGML-Spezifikation und verwerfen Dokumente mit
   solchen Fehlern.

   Beispiel 3.9. Fehlerhafte SGML-Kommentare

 <!-- Innerhalb eines Kommentars --

      DIES IST NICHT TEIL EINES KOMMENTARS

   -- Wieder innerhalb eines Kommentars -->

   SGML-Parser wu:rden die mittlere Zeile wie folgt interpretieren:

 <!DIES IST NICHT TEIL EINES KOMMENTARS>

   Da es sich hierbei nicht um gu:ltiges SGML handelt, kann diese Zeile zur
   verwirrenden Fehlermeldungen fu:hren.

 <!----- Eine wirklich schlechte Idee  ----->

   Wie das Beispiel zeigt, sollten solche Kommentare tunlichst vermieden
   werden.

 <!--===================================================-->

   Ein solcher Kommentar ist (ein wenig) besser, kann aber jemanden, der mit
   SGML noch nicht so vertraut ist, verwirren.

  3.5.1. Fingeru:bungen...

    1. Zur U:bung ko:nnen Sie einige Kommentare in die Datei beispiel.xml
       einfu:gen und u:berpru:fen, ob die Datei nun noch erfolgreich von
       onsgmls validiert werden kann.

    2. Zu Testzwecken sollten Sie auch noch ein paar fehlerhafte Kommentare
       hinzufu:gen und sich die resultierenden Fehlermeldungen von onsgmls
       ansehen.

3.6. Entita:ten

   Entita:ten stellen einen Mechanismus dar, mit dem einzelnen
   Dokumententeilen ein Name zugewiesen werden kann. Findet ein SGML-Parser
   wa:hrend des Parsens eine Entita:t, ersetzt er diese durch den ihr
   zugewiesenen Inhalt.

   Dadurch steht eine einfache Mo:glichkeit zur Verfu:gung, mit der variabler
   Inhalt in SGML-Dokumenten eingebunden werden kann. Zusa:tzlich sind
   Entita:ten der einzige Weg, u:ber den eine Datei in eine andere Datei mit
   SGML-Mitteln eingebunden werden kann.

   Es werden zwei Arten von Entita:ten unterschieden: Allgemeine Entita:ten
   und Parameterentita:ten.

  3.6.1. Allgemeine Entita:ten

   Allgemeine Entita:ten ko:nnen nur in Dokumenten benutzt werden. Sie
   ko:nnen zwar im SGML-Kontext definiert aber dort nicht benutzt werden.
   Vergleichen Sie dies mit Im Parameterentita:ten.

   Jede allgemeine Entita:t hat einen Namen, u:ber den sie angesprochen
   werden kann, um den von ihr referenzierten Inhalt in ein Dokument
   einzubinden. Dafu:r muss an der betreffenden Stelle der Namen der Entita:t
   per &entitaetenname; einfu:gt werden. Eine Entita:t current.version
   ko:nnte beispielsweise durch die aktuelle Versionsnummer eines Programms
   ersetzt werden. Man ko:nnte also schreiben:

 <para>Die aktuelle Version des
   Programms ist &current.version;.</para>

   Wenn sich die Versionsnummer a:ndert, muss nur die Entita:t angepasst und
   anschliessend das Dokument neu erzeugt werden.

   Eine weitere Einsatzmo:glichkeit fu:r Allgemeine Entita:ten ist das
   Einbinden von Zeichen, die auf andere Weise nicht in ein SGML-Dokument
   eingefu:gt werden ko:nnten. Ein Beispiel fu:r solche Zeichen sind < und &,
   die normalerweise nicht direkt in SGML-Dokumenten erlaubt sind. Sto:sst
   ein SGML-Parser bei seiner Arbeit auf das Symbol <, nimmt er an, dass der
   Anfang eines Start- oder Endtags gefunden wurde. Bei einem & wird er
   annehmen, den Anfang einer Entita:t gefunden zu haben.

   Wenn eines der beiden Zeichen beno:tigt wird, werden daher die allgemeinen
   Entita:ten &lt; und &amp; verwendet.

   Allgemeine Entita:ten ko:nnen nur in einem SGML-Kontext definiert werden.
   U:blich ist es, dies direkt nach der DOCTYPE-Deklaration zu tun:

   Beispiel 3.10. Allgemeine Entita:ten festlegen

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY current.version    "3.0-RELEASE">
 <!ENTITY last.version       "2.2.7-RELEASE">
 ]>

   Wichtig ist an dieser Stelle, dass die DOCTYPE-Deklaration durch eine
   eckige Klammer am Ende der ersten Zeile erweitert wurde. Die beiden
   Entita:ten selber werden in den folgenden zwei Zeilen definiert, bevor in
   der letzten Zeile die eckige Klammer und die DOCTYPE-Deklaration wieder
   geschlossen werden.

   Die eckigen Klammern sind notwendig um festzulegen, dass man die u:ber
   DOCTYPE genannte DTD erweitern mo:chte.

  3.6.2. Parameterentita:ten

   Genau wie Allgemeine Entita:ten werden Parameterentita:ten eingesetzt um
   wiederverwendbare Inhaltsteile mit Namen zu versehen. Im Gegensatz zu
   Allgemeinen Entita:ten ko:nnen sie aber nur innerhalb eines SGML-Kontextes
   genutzt werden.

   Die Definition von Parameterentita:ten erfolgt a:hnlich zu der Allgemeiner
   Entita:ten. Sie werden lediglich mit %entitaetenname; anstelle von
   &entitaetenname; referenziert[6]. Wichtig ist, dass das %-Zeichen zwischen
   ENTITY und dem Entita:tennamen ein Teil der Definition ist.

   Beispiel 3.11. Parameterentita:ten festlegen

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % param.etwas "etwas">
 <!ENTITY % param.text "Text">
 <!ENTITY % param.neu  "%param.etwas mehr %param.text">
 ]>

  3.6.3. Fingeru:bungen...

    1. Fu:gen Sie in beispiel.xml eine Allgemeine Entita:t ein.

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
 <!ENTITY version "1.1">
 ]>

 <html>
   <head>
     <title>Eine HTML-Beispieldatei</title>
   </head>

   <body>
     <p>Das ist ein Absatz mit etwas Text.</p>

     <p>Das ist ein Absatz mit anderem Text.</p>

     <p align="right">Dieser Absatz wird rechtsbu:ndig
       ausgerichtet.</p>

     <p>Die aktuelle Version ist: &amp;version;</p>
   </body>
 </html>

    2. Validieren Sie diese Datei mit onsgmls

    3. O:ffnen Sie nun beispiel.xml mit Ihrem Webbrowser. Es kann notwendig
       sein, dass Sie die Datei vorher in beispiel.html umbenennen mu:ssen,
       damit die Datei auch als HTML-Dokument erkannt wird.

       Nur wenn Sie einen sehr modernen Browser haben, werden Sie sehen
       ko:nnen, dass &version; durch die Versionsnummer ersetzt wurde. Leider
       haben die meisten Webbrowser sehr einfache SGML-Parser, die nicht
       richtig mit SGML umgehen ko:nnen[7].

    4. Die Lo:sung hierfu:r ist, das Dokument zu normalisieren. Zu diesem
       Zweck liest ein Normer das Dokument ein und gibt anschliessend
       semantisch gleichwertiges SGML wieder aus, dass auf verschiedene Arten
       transformiert worden sein kann. Eine dieser mo:glichen
       Transformationen ist das Ersetzen der Referenzen auf Entita:ten mit
       dem von ihnen pra:sentierten Inhalt.

       Versuchen Sie, die Beispieldatei mittels osgmlnorm zu normalisieren:

 % osgmlnorm beispiel.xml > beispiel.html

       Anschliessend sollten Sie eine normalisierte Version, dass heisst
       eine, bei der die Entita:ten gegen ihren Inhalt ersetzt wurden, in der
       Datei beispiel.html finden. Diese Datei ko:nnen Sie sich nun mit Ihrem
       Browser ansehen.

    5. Wenn Sie sich die Ausgaben von osgmlnorm ansehen, werden Sie
       feststellen, dass die DOCTYPE-Deklaration am Anfang der Datei nicht
       mehr enthalten ist. Mo:chten Sie die Deklaration behalten, muss
       osgmlnorm mit der Option -d aufrufen werden:

 % osgmlnorm -d beispiel.xml > beispiel.html

3.7. Dateien mit Entita:ten einbinden

   Sowohl Allgemeine als auch Parameterentita:ten sind nu:tzliche Helfer,
   wenn es darum geht, eine Datei in eine andere einzubinden.

  3.7.1. Dateien mit Allgemeinen Entita:ten einbinden

   Angenommen man hat ein Buch geschrieben, dessen Inhalt auf mehrere Dateien
   aufgeteilt und mittels SGML ausgezeichnet. Jedes Kapitel wurde dazu in
   einer eigenen Datei (kapitel1.xml, kapitel2.xml usw.) abgelegt und u:ber
   eine Datei buch.xml sollen alle physischen Dateien wieder mit der Hilfe
   von Entita:ten zu einem logischen Dokument zusammengefu:hrt werden.

   Damit der Inhalt der Dateien mit Entita:ten eingebunden werden kann, muss
   die Deklaration der Entita:ten das Schlu:sselwort SYSTEM enthalten.
   SGML-Parser werden so angewiesen, den Inhalt der referenzierten Datei als
   Wert fu:r die jeweilige Entita:t zu nehmen.

   Beispiel 3.12. Dateien mit Allgemeinen Entita:ten einbinden

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY kapitel.1 SYSTEM "kapitel1.xml">
 <!ENTITY kapitel.2 SYSTEM "kapitel2.xml">
 <!ENTITY kapitel.3 SYSTEM "kapitel3.xml">
 ]>

 <html>

   &amp;kapitel.1;
   &amp;kapitel.2;
   &amp;kapitel.3;
 </html>

  Warnung:

   Wenn man Allgemeine Entita:ten benutzt, um andere Dateien einzubinden,
   du:rfen diese Dateien (kapitel1.xml, kapitel2.xml, ...) keine eigene
   DOCTYPE-Deklaration haben.

  3.7.2. Dateien mit Parameterentita:ten einbinden

   Wie bereits festgestellt, ko:nnen Parameterentita:ten nur innerhalb eines
   SGML-Kontexts genutzt werden. Warum mo:chte man aber Dateien innerhalb
   eines SGML-Kontexts einbinden? Der Vorteil liegt in der Mo:glichkeit, die
   Deklaration von Entita:ten in eine andere Datei auslagern zu ko:nnen,
   wodurch diese leichter wiederverwendbar sind.

   Angenommen das Buch aus dem vorherigen Kapitel besteht aus sehr vielen
   Kapiteln und diese sollen auch in einem anderen Buch, aber in einer
   anderen Reihenfolge, verwendet werden. Eine Mo:glichkeit wa:re es, die
   dafu:r notwendigen Entita:ten am Anfang jedes Buches einzeln festzulegen -
   was allerdings mit der Zeit unhandlich und fehlertra:chtig wird.

   Alternativ bietet sich dazu an, die Deklarationen in eine separate Datei
   auszulagern und deren Inhalt anschliessend in beide Bu:cher u:ber
   Parameterentita:ten einzubinden.

   Beispiel 3.13. Dateien mit Parameterentita:ten einbinden

   Zuerst werden die Entita:ten in einer separaten Datei namens kapitel.ent
   deklariert. kapitel.ent entha:lt fu:r dieses Beispiel die folgenden
   Zeilen:

 <!ENTITY kapitel.1 SYSTEM "kapitel1.xml">
 <!ENTITY kapitel.2 SYSTEM "kapitel2.xml">
 <!ENTITY kapitel.3 SYSTEM "kapitel3.xml">

   Im zweiten Schritt fu:gt man in beide Bu:cher eine Parameterentita:t ein,
   die den Inhalt von kapitel.ent referenziert, und la:dt u:ber diese dann
   die Deklarationen. Anschliessend ko:nnen die so geladenen Entita:ten wie
   gewohnt genutzt werden.

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % kapitel SYSTEM "kapitel.ent">
 %kapitel;
 ]>

 <html>
   &amp;kapitel.1;
   &amp;kapitel.2;
   &amp;kapitel.3;
 </html>

  3.7.3. Fingeru:bungen...

    3.7.3.1. Binden Sie Dateien u:ber Allgemeine Entita:ten ein

    1. Legen Sie drei Dateien (absatz1.xml, absatz2.xml und absatz3.xml) mit
       jeweils einer Zeile wie

 <p>Erster Absatz.</p>

       an.

    2. A:ndern Sie beispiel.xml so ab, dass sie wie folgt aussieht:

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY version "1.1">
 <!ENTITY absatz1 SYSTEM "absatz1.xml">
 <!ENTITY absatz2 SYSTEM "absatz2.xml">
 <!ENTITY absatz3 SYSTEM "absatz3.xml">
 ]>

 <html>
   <head>
     <title>Eine HTML-Beispieldatei</title>
   </head>

   <body>
     <p>Die aktuelle Version dieses Dokuments ist &version;</p>

     &absatz1;
     &absatz2;
     &absatz3;
   </body>
 </html>

    3. Erzeugen Sie nun die Datei beispiel.html, indem Sie beispiel.xml
       normalisieren:

 % osgmlnorm -d beispiel.xml > beispiel.html

    4. O:ffnen Sie beispiel.html nun mit einem Webbrowser und vergewissern
       Sie sich, dass der Inhalt der Dateien absatzN.xml in beispiel.html
       u:bernommen wurde.

    3.7.3.2. Binden Sie Dateien mit Parameterentita:ten ein

  Anmerkung:

   Hierfu:r mu:ssen Sie die vorherige Fingeru:bung gemacht haben.

    1. A:ndern Sie beispiel.xml so ab, dass es wie folgt aussieht:

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % entitaeten SYSTEM "entitaeten.xml"> %entitaeten;
 ]>

 <html>
   <head>
     <title>Eine HTML-Beispieldatei</title>
   </head>

   <body>
     <p>Die aktuelle Version dieses Dokuments ist &version;</p>

     &absatz1;
     &absatz2;
     &absatz3;
   </body>
 </html>

    2. Legen Sie eine weitere Datei entitaeten.xml an, die folgenden Inhalt
       hat:

 <!ENTITY version "1.1">
 <!ENTITY absatz1 SYSTEM "absatz1.xml">
 <!ENTITY absatz2 SYSTEM "absatz2.xml">
 <!ENTITY absatz3 SYSTEM "absatz3.xml">

    3. Erzeugen Sie die Datei beispiel.html, indem Sie beispiel.xml
       normalisieren:

 % osgmlnorm -d beispiel.xml > beispiel.html

    4. O:ffnen Sie beispiel.html nun mit einem Webbrowser und vergewissern
       Sie sich, dass der Inhalt der Dateien absatzN.xml in beispiel.html
       u:bernommen wurde.

3.8. Markierte Bereiche

   SGML erlaubt es, dass bestimmte Dokumentabschnitte wa:hrend der
   Verarbeitung besonders behandelt werden sollen. Diese Abschnitte werden
   als "markierte Bereiche" [8] bezeichnet.

   Beispiel 3.14. Aufbau eines markierten Bereiches

 <![ SCHLU:SSELWORT [
   Inhalt des markierten Bereiches
 ]]>

   Da es sich bei markierten Bereichen um SGML-Konstrukte handelt, werden sie
   mit <! eingeleitet. Der eigentliche Anfang des markierten Bereiches wird
   von der folgenden eckigen Klammer bestimmt. Das darauf folgende
   SCHLU:SSELWORT legt fest, wie der "markierte Inhalt" durch einen
   SGML-Prozessor wa:hrend der Verarbeitung behandelt werden soll. Der
   "markierte" Inhalt selbst beginnt erst nach der zweiten eckigen Klammer
   und erstreckt sich bis zu den zwei schliessenden eckigen Klammern am Ende
   des Bereiches. Mit Hilfe des > Zeichens wird der mit <! begonnene
   SGML-Kontext wieder verlassen.

  3.8.1. Schlu:sselworte fu:r markierte Bereiche

    3.8.1.1. CDATA und RCDATA

   Die Schlu:sselworte CDATA und RCDATA bestimmen das Inhaltsmodell fu:r
   markierte Bereiche. Dadurch ist es mo:glich, vom Standardmodell
   abzuweichen.

   Ein SGML-Prozessor muss wa:hrend der Verarbeitung eines Dokuments zu jedem
   Zeitpunkt wissen, welches Inhaltsmodell gerade anzuwenden ist.

   Was ist ein Inhaltsmodell? Kurz gesagt beschreibt das Inhaltsmodell,
   welche Art von Inhalt der Parser zu erwarten und wie er damit umzugehen
   hat.

   Bei CDATA und RCDATA handelt es sich wahrscheinlich um die nu:tzlichsten
   Inhaltsmodelle. CDATA steht fu:r Zeichendaten[9]. Trifft ein Parser auf
   dieses Inhaltsmodell, wird er annehmen, dass sich im zugeho:rigen
   Dokumentenbereich nur "gewo:hnliche" Zeichen befinden. Das bedeutet, dass
   < und & ihre besondere Bedeutung verlieren und als einfache Zeichen
   behandelt werden.

   RCDATA steht fu:r Entita:tenreferenzen und Zeichendaten[10]. Fu:r einen
   Bereich mit diesem Inhaltsmodell, wird ein Parser davon ausgehen, dass er
   sowohl Zeichen als auch Enita:tenreferenzen finden kann. < verliert hier
   zwar auch seine besondere Bedeutung, doch & wird weiterhin als Anfang
   einer Entita:t interpretiert.

   Nu:tzlich ist das CDATA-Modell vor allem dann, wenn es darum geht Texte
   eins-zu-eins zu u:bernehmen, in denen < und & geha:uft auftreten. Zwar
   kann man solche Texte u:berarbeiten und jedes < durch ein &lt; und jedes &
   durch ein &amp; ersetzen, doch es wird in den meisten Fa:llen einfacher
   sein, fu:r den betreffenden Text CDATA als Inhaltsmodell festzulegen. Ein
   SGML-Parser wird dann, sobald er auf < oder & trifft, diese als Zeichen in
   einem Text betrachten.

  Anmerkung:

   Bei der Verwendung von CDATA und RCDATA als Inhaltsmodell fu:r
   SGML-Beispiele, wie sie in diesem Dokument enthalten sind, muss bedacht
   werden, dass der Inhalt eines CDATA-Bereiches nicht validiert wird. dass
   das SGML in diesen Bereichen gu:ltig ist, muss auf andere Weise
   sichergestellt werden. Denkbar ist beispielsweise, es in einem separaten
   Dokument zu erstellen, dort zu pru:fen und erst dann in das eigentliche
   Dokument einzufu:gen.

   Beispiel 3.15. CDATA als Inhaltsmodell fu:r markierte Bereiche

 <para>Das ist ein Beispiel, wie man einen Text,
   der viele &lt;- und &amp;-
   Entita:ten entha:lt, in ein Dokument einbinden kann.
   Das Beispiel selbst, das sich innerhalb des markierten Bereiches befindet,
   ist ein HTML-Fragment. Der diesen Text umschliessende Tag, beginnend mit
   mit para und endend mit /para, stammt aus der DocBook DTD.</para>

 <programlisting>
   <![RCDATA[ 
     <p>Dieses Beispiel demonstriert die Verwendung von HTML-Elementen.
       Da spitze Klammern so oft vorkommen, ist es einfacher, das
       gesamte Beispiel als CDATA Abschnitt auszuweisen, als die
       entsprechenden Entita:ten zu nutzen.</p>

     <ul>
       <li>Das ist ein Listenelement.</li>
       <li>Das ist ein zweites Listenelement.</li>
       <li>Das ist ein drittes Listenelement.</li>
     </ul>

     <p>Und das hier, das ist das Ende des Beispiels.</p>
   ]]>
 </programlisting>

   Liest man die Quellen dieser Fibel, wird man feststellen, dass diese
   Technik durchga:ngig angewandt wurde.

    3.8.1.2. INCLUDE und IGNORE

   Das Schlu:sselwort INCLUDE legt fest, dass der Inhalt des betreffenden
   Abschnittes mitverarbeitet wird. Demgegenu:ber bestimmt IGNORE, dass er
   ignoriert wird, dass heisst, dass er bei der Verarbeitung u:bergangen wird
   und in der Ausgabe nicht enthalten ist.

   Beispiel 3.16. Anwendung von INCLUDE und IGNORE in markierten Abschnitten

 <![ INCLUDE [
   Dieser Text wird verarbeitet und eingebunden.
 ]]>

 <![ IGNORE [
   Dieser Text wird weder verarbeitet noch eingebunden.
 ]]>

   Fu:r sich alleine ist IGNORE als Anweisung nicht besonders nu:tzlich, da
   ein Bereich, der von der Verarbeitung ausgenommen sein soll, auch
   auskommentiert werden kann.

   Kombiniert man IGNORE hingegen mit Parameterentita:ten, steht so ein Weg
   zur Verfu:gung, um dessen Anwendung besser steuern zu ko:nnen. Zwar
   ko:nnen Parameterentita:ten nur in einem SGML-Kontext einsetzt werden, da
   aber markierte Bereiche ebenfalls SGML-Konstrukte sind, ist diese
   Einschra:nkung irrelevant.

   Soll beispielsweise ein und dasselbe Dokument in zwei unterschiedlichen
   Varianten produziert werden, einer gedruckten und einer digitalen, und
   soll nur die digitale zusa:tzliche Informationen enthalten, kann dies mit
   einem Trick erreicht werden.

   Man definiert eine Parameterentita:t, der man als Wert die Zeichenkette
   INCLUDE zuweist und deklariert den betreffenden Bereich, der nur in der
   digitalen Variante erscheinen soll, als markierten Abschnitt und setzt als
   Schlu:sselwort die zuvor definierte Parameterentita:t ein.

   Soll anstelle der digitalen die gedruckte Variante produziert werden, muss
   lediglich der Entita:t IGNORE als Wert zugewiesen und das
   Ursprungsdokument erneut durch den SGML-Prozessor geschickt werden.

   Beispiel 3.17. Kontrolle von markierten Bereichen u:ber
   Parameterentita:ten

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % digitale.kopie "INCLUDE">
 ]]>

 ...

 <![ %digitale.kopie [
   Dieser Satz sollte nur in der digitalen Version enthalten sein.
 ]]>      

   Bei der Produktion der gedruckten Variante muss der Wert der Entita:t
   gea:ndert werden.

 <!ENTITY % digitale.kopie "IGNORE">

   Bei der Verarbeitung wird als Schlu:sselwort in beiden Fa:llen der von
   %digitale.kopie repra:sentierte Wert verwendet. Im ersten Fall wird der
   Inhalt des markierten Bereichs mitverarbeitet, im zweiten Fall nicht.

  3.8.2. Fingeru:bung...

    1. Legen Sie eine neue Datei abschnitt.xml an, die folgenden Inhalt hat:

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % text.ausgabe "INCLUDE">
 ]>

 <html>
   <head>
     <title>Ein Beispiel mit markierten Abschnitten</title>
   </head>

   <body>
     <p>Dieser Absatz <![CDATA[beinhaltet viele <
       Zeichen (< < < < <). Weshalb es einfacher ist,
       ihn als CDATA Bereich auszuweisen. ]]></p>

     <![ IGNORE [
     <p>Dieser Absatz wird NICHT in der Ausgabe enthalten sein.</p>
     ]]>

     <![ %text.ausgabe [
      <p>Dieser Absatz wird in Abha:ngigkeit von %text.ausgabe
        mitausgegeben.</p>
     ]]>
   </body>
 </html>

    2. Normalisieren Sie den Inhalt dieser Datei mit Hilfe von osgmlnorm und
       sehen Sie sich das Ergebnis an. Achten Sie dabei darauf, welche
       Absa:tze enthalten beziehungsweise nicht enthalten sind und was aus
       den CDATA-Bereichen geworden ist.

    3. A:ndern Sie die Definition von text.ausgabe so, dass es den Wert
       IGNORE zugewiesen bekommt. Verarbeiten Sie dann die Datei erneut mit
       osgmlnorm und vergleichen die Ausgabe mit der vom ersten osgmlnorm
       Lauf.

3.9. Schlussbemerkung

   Aus Platzgru:nden, und um der Versta:ndlichkeit Willen, wurden viele
   Gesichtspunkte nicht in aller Tiefe beziehungsweise gar nicht besprochen.
   Trotzdem sollte in den bisherigen Kapiteln genu:gend Wissen u:ber SGML
   vermittelt worden sein, um den Aufbau der Dokumentation des FDPs zu
   verstehen.

     ----------------------------------------------------------------------

   [1] Im angelsa:chsischen Sprachraum wird von 'markup` gesprochen.

   [2] Bei natu:rlichen Sprachen spricht man vom Satzbau - demjenigen
   Konstrukt, das unter anderem die Position des Subjekts, Objekts und
   Pra:dikats in einem Satz festlegt.

   [3] Im angelsa:chsischen Sprachraum wird hier von "chunking" gesprochen.

   [4] Sofern man nicht an der deutschen Dokumentation arbeitet, mu:ssen die
   Verzeichnisangaben entsprechend angepasst werden.

   [5] auf Englisch Formal Public Identifier (FPI)

   [6] Es wird das Prozentzeichen anstelle des kaufma:nnischen Unds
   verwendet.

   [7] Eigentlich ist das eine Schande. Man stelle sich vor, welche Probleme
   und Hacks, wie beispielsweise Server Side Includes, man an dieser Stelle
   ha:tte vermeiden ko:nnen.

   [8] auf Englisch marked sections

   [9] auf Englisch character data

   [10] auf Englisch Entity references and character data

                       Kapitel 4. XML-Dokumente erstellen

   Inhaltsverzeichnis

   4.1. XHTML

   4.2. Die DocBook DTD

   In diesem Kapitel werden die beiden vom FDP eingesetzten
   Auszeichnungssprachen XHTML und DocBook behandelt. Hierbei beschra:nkt
   sich dieses Kapitel auf die Elemente, die bei der ta:glichen Arbeit am
   ehesten zum Einsatz kommen werden.

   Beide Sprachen besitzen eine grosse Anzahl von Elementen. Das erschwert
   es, das richtige Element in der richtigen Situation auszuwa:hlen. Aus
   diesem Grund werden zu jedem Element auch immer Beispiele angeboten, die
   den richtigen Einsatz des Elements verdeutlichen sollen.

   Es ist nicht das Ziel dieses Kapitels mo:glichst viele Elemente beider
   Sprachen zu behandeln - dies wa:re nur eine Wiederholung der eigentlichen
   Sprachreferenz. Sofern es Unklarheiten zur Verwendung einzelner Elemente
   und Auszeichnung von bestimmten Sachverhalten gibt, ko:nnen diese an
   FreeBSD documentation project geschickt werden.

  Fluss- kontra Blockelemente:

   Wenn im Folgenden von Flusselementen die Rede ist, sind damit Elemente
   gemeint, die in einem Blockelement auftreten ko:nnen und keinen
   Zeilenumbruch hervorrufen. Blockelemente hingegen erzeugen unter anderem
   einen Zeilenumbruch[11].

4.1. XHTML

   XHTML ist die XML Version der HyperText Markup Language, der
   Auszeichnungssprache der Wahl im World Wide Web. Weitere Informationen zu
   XHTML finden sich unter http://www.w3.org/.

   XHTML kommt bei der Erstellung der Webseiten des FreeBSD-Projektes zum
   Einsatz. Fu:r technische Dokumentationen sollte XHTML jedoch nicht
   eingesetzt werden, da DocBook eine gro:ssere und bessere Auswahl an
   Elementen bietet. Folglich sollte XHTML nur fu:r die FreeBSD-Webseiten
   verwendet werden.

   Die HTML-Spezifikation liegt bis jetzt in mehreren Versionen vor: 1, 2,
   3.0, 3.2, 4.0 sowie eine XML konforme Version namens XHTML in seiner
   neuesten Version XHTML 1.0 (verfu:gbar als strict und transitional
   Variante.

   Die XHTML-DTDs sind u:ber den Port textproc/xhtml verfu:gbar und werden
   automatisch als Teil des Metaports textproc/docproj installiert.

  4.1.1. Formale O:ffentliche Bezeichner

   Da es mehrere Version von XHTML gibt, existieren auch mehrere FO:Ps, zu
   denen ein XHTML-Dokument konform erkla:rt werden kann. Die Mehrzahl der
   sich auf der FreeBSD-Webseite befindenden XHTML-Seiten sind zu der
   lockeren Version von XHTML 1.0 konform.

 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

  4.1.2. Die Elemente head und body

   Ein XHTML-Dokument unterteilt sich normalerweise in zwei Bereiche: "head"
   und "body". Der Kopf (head) entha:lt Metadaten wie den Dokumententitel und
   Angaben zum Autor. Der Rumpf (body) umfasst den eigentlichen
   Dokumenteninhalt, der fu:r den Leser bestimmt ist. In einem XHTML-Dokument
   werden diese Bereiche u:ber die Elemente head und body voneinander
   abgegrenzt. Beide sind Kinder des Wurzelelementes html.

   Beispiel 4.1. Die Struktur eines XHTML-Dokumentes

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <title>Der Dokumententitel</title>
   </head>

   <body>

     ...

   </body>
 </html>

  4.1.3. Blockelemente

    4.1.3.1. U:berschriften

   XHTML kennt sechs verschiedene Elemente, mit denen U:berschriften
   ausgezeichnet werden ko:nnen. Das bekannteste Element ist h1, das sich am
   Anfang der U:berschriftenhierarchie befindet. h1 folgen die
   U:berschriftenelemente h2 bis h6. Der Inhalt von hN stellt den Text der
   U:berschrift dar.

   Beispiel 4.2. h1, h2...

   Fu:gen Sie in eine der existierenden U:bungsdateien folgendes ein:

 <h1>Erstes Kapitel</h1>

 <!-- Hier steht die Einfu:hrung -->

 <h2>Das ist die U:berschrift des ersten Kapitels</h2>

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

 <h3>Das ist die U:berschrift des ersten Unterkapitels</h3>

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

 <h2>Das ist die U:berschrift des zweiten Kapitels</h2>

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

   Eine XHTML-Seite sollte immer nur eine U:berschrift h1 haben. Dieser
   U:berschrift ko:nnen beliebig viele Kapitel mit einer U:berschrift h2
   folgen, die selbst wiederum eine beliebige Anzahl von Kapiteln mit einer
   U:berschrift h3 enthalten ko:nnen. Diese Verschachtelung setzt sich bis zu
   Kapiteln mit einer h6-U:berschrift fort. Es sollte vermieden werden,
   Elemente in der U:berschriftenhierarchie auszulassen.

   Beispiel 4.3. Falsche Verschachtelung von U:berschriften

   Fu:gen Sie in eine der existierenden U:bungsdateien folgendes ein:

 <h1>Erstes Kapitel</h1>

 <!-- Allgemeines zum Dokument -->

 <h3>Unterkapitel</h3>

 <!-- h3 folgt direkt auf h1. h2 wurde ausgelassen -->

    4.1.3.2. Absa:tze

   Absa:tze ko:nnen in XHTML mit Hilfe des Elementes p ausgezeichnet werden.

   Beispiel 4.4. Absa:tze mit dem Element p

   Fu:gen Sie in eine der existierenden U:bungsdateien folgendes ein:

 <p>Das hier, das ist ein Absatz. Absa:tze ko:nnen
   andere Elemente enthalten.</p>

    4.1.3.3. Blockzitate

   Ein Blockzitat ist ein etwas umfangreicheres Zitat aus einem anderen Text,
   das nicht zum aktuellen Absatz geho:rt.

   Beispiel 4.5. Blockzitat

   Fu:gen Sie in eine der existierenden U:bungsdateien folgendes ein:

 <blockquote>
   <p>Artikel 1: Menschenwu:rde; Grundrechtsbindung der
     staatlichen Gewalt</p>

   <ol>
     <li>
       <p>Die Wu:rde des Menschen ist unantastbar. Sie zu achten
         und zu schu:tzen ist Verpflichtung aller staatlichen
         Gewalten.</p>
     </li>
     <li>
       <p>Das Deutsche Volk bekennt sich darum zu unverletzlichen
         und unvera:usserlichen 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>

    4.1.3.4. Listen

   XHTML kennt drei Arten von Listen: sortierte, unsortierte und
   Definitionslisten. Ein Eintrag in einer sortierten Liste wird
   u:blicherweise mit einer Nummer versehen, Eintra:ge in unsortierten Listen
   hingegen mit einem Aufza:hlungspunkt. Definitionslisten wiederum bestehen
   aus zwei Teilen: Der erste entha:lt den Begriff der definiert werden soll
   und der zweite dessen Erla:uterung.

   Sortierte Listen werden mit dem Element ol (fu:r ordered list)
   ausgezeichnet, unsortierte Listen mit ul (fu:r unordered list) und
   Definitionslisten mit dl.

   Listenpunkte sortierter und unsortierter Listen werden mit dem Element li
   ausgezeichnet, welches Text oder andere Blockelemente enthalten kann.
   Begriffe, die in einer Definitionslisten enthalten sind, werden mit dem
   Element dt (fu:r definition term) ausgezeichnet. Die Erkla:rung zu diesem
   Begriff wird mit Hilfe des Elementes dd (fu:r definition description)
   markiert. So wie li, kann das Element dd ebenfalls andere Blockelemente
   aufnehmen.

   Beispiel 4.6. Listen mit ul und ol erstellen

   Fu:gen Sie in eine der existierenden U:bungsdateien folgendes ein:

 <p>Jetzt folgt eine unsortierte Liste. Wahrscheinlich werden
   die einzelnen Eintra: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 Eintra:ge bestehen aus mehreren Absa: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>

   Beispiel 4.7. Definitionslisten mit dl erstellen

   Fu:gen Sie in eine der existierenden U:bungsdateien folgendes ein:

 <dl>
   <dt>Erster Begriff</dt>

   <dd><p>Erster Absatz der Erkla:rung</p>

     <p>Zweiter Absatz der Erkla:rung.</p></dd>

   <dt>Zweiter Begriff</dt>

   <dd><p>Erster Absatz der Erkla:rung.</p></dd>

   <dt>Dritter Begriff</dt>

   <dd>Erster Absatz der Erkla:rung zum dritten Begriff.</dd>
 </dl>

    4.1.3.5. Vorformatierter Text

   In einigen Fa:llen ist es gewollt, dass die Formatierung eines Textes im
   Quelldokument erhalten bleibt, damit der Leser diesen genau so sieht, wie
   ihn der Autor erstellt hat. In der XHTML-Spezifikation ist dafu:r das
   Element pre vorgesehen, welches dafu:r sorgt, dass Zeilenumbru:che
   erhalten bleiben und Leerzeichen nicht zusammengefasst werden. Browser
   verwenden fu:r den Inhalt des Elementes pre u:blicherweise eine
   Fixschrift.

   Beispiel 4.8. Vorformatierten Text mit pre erstellen

   Der Originaltext einer E-Mail la:sst sich beispielsweise wie folgt
   einbinden:

 <pre>  From: nik@FreeBSD.org
   To: freebsd-doc@FreeBSD.org
   Subject: Neue Version verfu:gbar

   Es ist eine neue Version der Fibel fu:r neue Mitarbeiter am
   FreeBSD-Dokumentationsprojekt verfu:gbar:

     &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;

   Kommentare und Anmerkungen sind willkommen.

   N</pre>

   Beachten Sie, dass < und & nach wie vor als Sonderzeichen erkannt werden.
   Daher wird in diesem Beispiel auch &lt; an Stelle von < verwendet. Aus dem
   gleichen Grund wurde auch &gt; an Stelle von > verwendet. Achten Sie also
   stets auf Sonderzeichen, wenn Sie normalen Text aus E-Mails, Programmcode
   oder einer anderen Quelle kopieren.

    4.1.3.6. Tabellen

  Anmerkung:

   Die meisten Textbrowser, beispielsweise Lynx, ko:nnen Tabellen nicht
   besonders gut darstellen. Deshalb sollten Auszeichnungsalternativen in
   Betracht gezogen werden, um eine angemessene Darstellung sicherzustellen.

   Tabellen lassen sich in XHTML mit Hilfe des Elements table auszeichnen.
   Eine Tabelle setzt sich aus einer oder mehreren Zeilen (tr) zusammen, von
   denen jede mindestens eine Zelle (td) entha:lt. Zellen ko:nnen wiederum
   andere Blockelemente, wie Absa:tze oder Listen, enthalten. Auch ko: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 p zu umschliessen.

   Beispiel 4.9. Einfache Tabelle mit table

   Fu:gen Sie in eine der existierenden U:bungsdateien folgendes ein:

 <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>

   XHTML kennt die Mo:glichkeit, dass sich eine Zelle mehrere Zeilen und/oder
   Spalten erstrecken kann. Sollen beispielsweise mehrere Spalten
   zusammenfassen werden, kann dies mit Hilfe des Attributes colspan erreicht
   werden, indem man ihm die Anzahl der zusammenzufassenden Spalten zuweist.
   A:hnliches gilt fu:r die Zusammenfassung von Zeilen: Hierfu:r wird dem
   Attribut rowspan die Anzahl der zusammenzufassenden Zeilen zugewiesen.

   Beispiel 4.10. Anwendung des Attributes rowspan

 <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 du:nn</td>
   </tr>

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

     <td>Untere Zelle</td>
   </tr>
 </table>

   Beispiel 4.11. Anwendung des Attributes colspan

 <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>

   Beispiel 4.12. Gemeinsame Anwendung der Attrbute rowspan und colspan

 <p>Eine Tabelle mit 3-mal-3 Zellen. Oben links
   werden 2 mal 2 Zelle zusammengezogen.</p>

 <table>
   <tr>
     <td colspan="2" rowspan="2">Grosse obere linke Zelle</td>

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

   <tr>
     <td>Mittlere rechte Zelle</td>
   </tr>

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

     <td>Untere mittlere Zelle</td>

     <td>Untere rechte Zelle</td>
   </tr>
 </table>

  4.1.4. Flusselemente

    4.1.4.1. Hervorheben von Information

   Sollen sich bestimmte Informationen von anderen optisch abheben, kann dies
   mit den HTML-Tags strong und em erreicht werden. strong stellt dabei eine
   sta:rkere Hervorhebung als em dar, wobei mit strong ausgezeichnete
   Elemente fett und mit em ausgezeichnete Elemente kursiv dargestellt
   werden. Allerdings ist diese Aussage nicht verla:sslich, da die
   Darstellung vom Browser abha:ngig ist. In der Praxis ist es so, dass
   Webseiten nur strukturelle und semantische Informationen enthalten und
   Stylesheets spa:ter auf diese Informationen angewendet werden. Beachten
   Sie also die Semantik und nicht die Formatierung wenn Sie mit diesen Tags
   arbeiten.

   Beispiel 4.13. Text mit em und strong hervorheben

 <p><em>Dieses</em> Wort ist hervorgehoben,
   wa:hrend <strong>dieses noch sta:rker hervorgehoben ist.</p>

    4.1.4.2. Nicht-proportionale Schrift fu:r Texte

   Der Tag tt erlaubt es, Text in einer schreibmaschinena:hnlichen Schrift
   darzustellen.

   Beispiel 4.14. Nicht-proportionale Schrift mit tt

 <p>Dieses Dokument wurde urspru:nglich von
   Nik Clayton geschrieben. Nick Clayton kann unter der E-Mail-Adresse
   <tt>nik@FreeBSD.org</tt> erreicht werden.</p>

  4.1.5. Links

  Anmerkung:

   Bei Links handelt es sich ebenfalls Flusselemente.

    4.1.5.1. Auf andere Dokumente im WWW verweisen

   Um auf ein anderes Dokument im WWW zu verweisen, mu:ssen Sie die URL
   dieses Dokuments kennen.

   Links auf andere Dokumente im WWW werden in HTML durch den Tag a und
   dessen Attribute href, das die Zieladresse entha:lt, angelegt. Der Inhalt
   des Elementes wird selbst zum Link und seine Darstellung erfolgt
   verschieden vom u:brigen Text. Meist geschieht das durch eine andere
   Schriftfarbe oder dadurch, dass der Linktext unterstrichen wird.

   Beispiel 4.15. <a href="..."> benutzen

 <p>Weitere Informationen stehen auf der
   <a href="http://www.FreeBSD.org/">FreeBSD-Webseite</a> zur Verfu:gung.</p>

   Beim Aufruf dieses Links wird das referenzierte Dokument vom Browser
   geladen und mit dessen Seitenanfang dargestellt.

    4.1.5.2. Auf bestimmte Dokumentenabschnitte verweisen

   XHTML unterstu:tzt neben einfachen Links auch solche, die auf einen
   bestimmten Abschnitt innerhalb eines Dokumentes verweisen. Dazu mu:ssen
   die Abschnitte, auf die verwiesen werden soll, mit Hilfe von sogenannten
   "Ankern" markiert werden. Diese Anker ko:nnen ebenfalls mit Hilfe des Tags
   a gesetzt werden, nur das anstelle von href das Attribut name gesetzt
   werden muss.

   Beispiel 4.16. Anwendung von <a id="...">

 <p><a name="absatz1">Auf</a> diesen Absatz kann mit
   Hilfe seines Namens (<tt>absatz1</tt>) verwiesen werden.</p>

   Um auf einen so gekennzeichneten Abschnitt zu verweisen, muss die URL des
   Dokumentes um das Zeichen # und den Namen des Zielankers erweitert werden.

   Beispiel 4.17. Auf einen Abschnitt eines anderen Dokumentes verweisen

   Fu:r dieses Beispiel wird davon ausgegangen, dass der mit absatz1
   gekennzeichnete Absatz sich in der XHTML-Datei foo.html befindet.

 <p>Weitere Informationen ko:nnen im
   <a href="foo.html#absatz1">ersten Absatz</a> der Datei
   <tt>foo.html</tt> gefunden werden.</p>

4.2. Die DocBook DTD

   DocBook wurde urspru:nglich von HaL Computer Systems und O'Reilly &
   Associates als DTD fu:r das Erstellen von technischen Dokumenten
   entwickelt [12]. Seit 1998 wird es vom DocBook Technical Committee
   gewartet. DocBook ist sehr stark auf die Beschreibung von Inhalten, und
   nicht auf die Darstellung des Inhalts ausgerichtet. Damit steht es im
   Gegensatz zu LinuxDoc und XHTML.

  Formelle und informelle Elemente:

   Einige Elemente der DocBook DTD sind in zwei Varianten vorhanden: formell
   und informell. U:blicherweise besitzt die formelle Variante einen Titel,
   dem der eigentliche Elementinhalt folgt. Die informelle Variante hingegen
   hat keinen Titel.

   Die DocBook DTD ist in der Ports-Sammlung im Port textproc/docbook
   enthalten und wird bei der Installation des Metaports textproc/docproj
   automatisch installiert.

  4.2.1. Die FreeBSD-Erweiterungen

   Fu:r das FDP wurde die DocBook DTD durch das FreeBSD-Dokumentationsproject
   um zusa:tzliche Elemente erweitert, um damit pra:zisiere
   Auszeichnungsmo:glichkeiten zur Verfu:gung zu haben. Sofern im folgenden
   FreeBSD-spezifische Elemente genutzt werden, wird explizit darauf
   hingewiesen werden.

   Wenn nachfolgend im Text der Begriff "DocBook" verwendet wird, ist damit
   die durch das FDP erweiterte Version der DocBook DTD gemeint.

  Anmerkung:

   Die durch das FDP vorgenommenen Erweiterungen sind nicht
   FreeBSD-spezifisch. Sie wurden lediglich vorgenommen, da sie fu:r die
   Arbeit des FDPs als nu:tzlich erschienen. Fu:r den Fall, das in den
   anderen *nix-Lagern (NetBSD, OpenBSD, Linux,...) Interesse daran besteht,
   gemeinsam eine Standarderweiterung fu:r die DocBook DTD zu entwickeln,
   kann mit dem Documentation Engineering Team <doceng@FreeBSD.org>
   Verbindung aufgenommen werden.

   Zum jetzigen Zeitpunkt sind die FreeBSD-Erweiterungen nicht Bestandteil
   der Ports-Sammlung. Sie werden im FreeBSD-Subversion-Repository
   (head/share/xml/freebsd.dtd) verwaltet.

  4.2.2. Formelle O:ffentliche Bezeichner

   In U:bereinstimmung mir der DocBook-Richtlinie zur Erstellung von
   Bezeichnern fu:r DocBook-Erweiterungen lautet der Bezeichner der
   erweiterten FreeBSD-Variante:

 PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"

  4.2.3. Die Struktur von DocBook-Dokumenten

   DocBook erlaubt es, Dokumente auf verschiedene Weise zu strukturieren.
   Innerhalb des FDPs werden hauptsa:chlich zwei Arten von DocBook-Dokumenten
   verwendet: Buch und Artikel. Beide unterscheiden sich darin, dass ein Buch
   auf der obersten Ebene durch chapter-Elemente strukturiert wird. Sollte
   das noch nicht ausreichend sein, ko:nnen die einzelnen Kapitel eines
   Buches mit Hilfe des Elementes part in Teile aufgespalten werden. Das
   Handbuch ist beispielsweise auf diese Weise aufgebaut.

   Kapitel (chapter) ko:nnen weiterhin in Unterkapitel unterteilt werden.
   Diese werden durch die Elemente sect1 ausgezeichnet. Soll ein Unterkapitel
   selbst weitere Unterkapitel enthalten, kann das u:ber das Element sect2
   geschehen. Diese Unterteilung kann bis zur Tiefe von fu:nf Unterkapiteln -
   u:ber die Elemente sect3, sect4 und sect5 - fortgefu:hrt werden. Der
   eigentliche Inhalt, um den es ja in dem Artikel oder Buch geht, wird
   unterhalb der hier genannten Elemente eingefu:gt.

   Vom Aufbau her ist ein Artikel einfacher strukturiert als ein Buch. So
   kann ein Artikel beispielsweise keine Kapitel (chapter) enthalten.
   Stattdessen kann der Inhalt eines Artikels nur durch die schon bekannten
   sectN-Elemente in einen oder mehrere Abschnitte gegliedert werden.
   U: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 fu:r Texte, die nicht in mehrere Kapitel aufgeteilt werden
   mu:ssen und mit einem Umfang von ungefa:hr 20 bis 25 Seiten
   vergleichsweise kurz sind. Natu:rlich ist das nur eine Richtlinie. Bu:cher
   sind dementsprechend am besten fu:r lange Texte geeignet, die sich
   sinnvoll in Kapitel unterteilen lassen und mo:glichweiser noch Anha:nge
   und a:hnliches enthalten ko:nnen.

   Alle Tutorien von FreeBSD sind als Artikel verfasst, wa:hrend hingegen die
   FreeBSD-FAQ und das FreeBSD-Handbuch als Bu:cher verfasst wurden.

    4.2.3.1. Bu:cher schreiben

   Der Inhalt eines Buches wird in einem book-Element abgelegt. Neben dem
   Textteil des Buches kann dieses Element weitergehende Informationen u:ber
   das Buch selbst, wie Meta-Informationen zum Erstellen eines
   Stichwortverzeichnisses oder zusa:tzliche Inhalte zum Erstellen einer
   Titelei, enthalten. Diese zusa:tzlichen Inhalte sollten in einem
   bookinfo-Element abgelegt werden.

   Beispiel 4.18. Buchvorlage book mit bookinfo

 <book>
   <bookinfo>
     <title>Titel</title>
     <author>
       <firstname>Vorname</firstname>
       <surname>Nachname</surname>
       <affiliation>
         <address><email>E-Mail-Adresse</email></address>
       </affiliation>
     </author>

     <copyright>
       <year>1998</year>
       <holder role="mailto:E-Mail-Adresse">Vollsta:ndiger Name</holder>
     </copyright>

     <releaseinfo>$FreeBSD$</releaseinfo>

     <abstract>
       <para>Kurze Zusammenfassung des Buchinhaltes.</para>
     </abstract>
   </bookinfo>

   ...

 </book>

    4.2.3.2. Artikel schreiben

   Der Inhalt eines Artikels wird in einem article-Element abgelegt. Neben
   dem Textteil kann dieses Element weitere Teile, wie Meta-Informationen zum
   Erstellen eines Stichwortverzeichnisses oder zusa:tzliche Inhalte zum
   Erstellen einer Titelei, enthalten. Analog zu einem Buch, sollten diese
   Informationen in einem articleinfo-Element abgelegt werden.

   Beispiel 4.19. Artikelvorlage article mit articleinfo

 <article>
   <articleinfo>
     <title>Titel</title>

     <author>
       <firstname>Vorname</firstname>
       <surname>Nachname</surname>
       <affiliation>
         <address><email>E-Mail-Adresse</email></address>
       </affiliation>
     </author>

     <copyright>
       <year>1998</year>
       <holder role="mailto:E-Mail-Adresse">Vollsta:ndiger Name</holder>
     </copyright>

     <releaseinfo>$FreeBSD$</releaseinfo>

     <abstract>
       <para>Kurze Zusammenfassung des Artikelinhalts.</para>
     </abstract>
   </articleinfo>

   ...

 </article>

    4.2.3.3. Kapitel

   Kapitel werden mit dem chapter-Element angelegt und mu:ssen ein
   title-Element enthalten. Verwendet werden ko:nnen sie nur in Bu:chern.

   Beispiel 4.20. Ein einfaches Kapitel

 <chapter>
   <title>Kapitelu:berschrift</title>

   &hellip;
 </chapter>

   Kapitel ko:nnen nicht leer sein. Neben einem title-Element mu:ssen sie
   weiteren Inhalt beinhalten. Falls ein leeres Kapitel beno:tig wird, kann
   dies durch das Einfu:gen eines leeren Absatzes (para) erreicht werden.

   Beispiel 4.21. Ein leeres Kapitel

 <chapter>
   <title>Das ist ein leeres Kapitel</title>

   <para></para>
 </chapter>

    4.2.3.4. Unterkapitel

   Bu:cher werden auf der obersten Gliederungsebene durch chapter-Elemente in
   Kapitel unterteilt. Eine weitergehende Untergliederung kann durch das
   Anlegen von Unterkapiteln erreicht werden. Im Gegensatz zu Kapiteln, die
   durch chapter-Elemente ausgezeichnet werden, erfolgt die Auszeichnung von
   Unterkapitel mit dem Element sectn. Das n in Elementnamen trifft eine
   Aussage u:ber die Gliederungstiefe, auf der sich das Unterkapitel
   befindet. Ein sect1-Element kann mehrere Elemente vom Typ sect2 enthalten,
   die die Unterkapitel der na:chsten Gliederungsebene darstellen. sect5 ist
   das letzte Element, das auf diese Art zur Gliederung eingesetzt werden
   kann.

   Beispiel 4.22. Unterkapitel

 <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>

  Anmerkung:

   Die Unterkapitel dieses Beispiels wurden zu Demonstrationszwecken manuell
   durchnummeriert. In "normalen" Dokumenten wird diese Aufgabe von den
   Stylesheets u:bernommen.

    4.2.3.5. Bu:cher mittels part unterteilen

   In den Fa:llen, in denen die Unterteilung eines Buches in Kapitel nicht
   ausreichend ist, ko:nnen mehrere Kapitel mit dem Element part zu einem
   Teil zusammengefasst werden.

 <part>
   <title>Einfu:hrung</title>

   <chapter>
     <title>U:berblick</title>

      &hellip;
   </chapter>

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

     &hellip;
   </chapter>

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

     &hellip;
   </chapter>
 </part>

  4.2.4. Blockelemente

    4.2.4.1. Absa:tze

   DocBook kennt drei Arten von Absa:tzen: Absa:tze mit U:berschrift
   (formalpara), normale Absa:tze (para) und einfache Absa:tze (simpara).

   Normale Absa:tze und einfache Absa:tze unterscheiden sich dadurch, dass
   innerhalb von para Blockelemente erlaubt sind, innerhalb von simpara
   hingegen nicht. Es ist empfehlenswert, para den Vorzug zu geben.

   Beispiel 4.23. Absatz mit para

 <para>Das ist ein Absatz. Absa:tze ko:nnen fast jedes andere
   Element aufnehmen.</para>

   Darstellung:

   Das ist ein Absatz. Absa:tze ko:nnen fast jedes andere Element aufnehmen.

    4.2.4.2. Blockzitate

   Blockzitate sind textlich umfangreichere Zitate aus einem anderen Text,
   die nicht innerhalb des aktuellen Absatzes angezeigt werden sollen.
   Wahlweise ko:nnen Blockzitate eine U:berschrift haben und die Zitatquelle
   nennen.

   Beispiel 4.24. blockquote

 <para>Ein Auszug aus dem Grundgesetz:</para>

 <blockquote>
   <title>Menschenwu:rde; Grundrechtsbindung der staatlichen Gewalt</title>

   <attribution>Aus dem Grundgesetz</attribution>

   <orderedlist>
     <listitem>
       <para>Die Wu:rde des Menschen ist unantastbar. Sie zu achten
         und zu schu:tzen ist Verpflichtung aller staatlichen
         Gewalten.</para>
     </listitem>
     <listitem>
       <para>Das Deutsche Volk bekennt sich darum zu unverletzlichen
         und unvera:usserlichen 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>

   Darstellung:

     Menschenwu:rde; Grundrechtsbindung der staatlichen Gewalt                
      1. Die Wu:rde des Menschen ist unantastbar. Sie zu achten und zu      
         schu:tzen ist Verpflichtung aller staatlichen Gewalten.            
                                                                            
      2. Das Deutsche Volk bekennt sich darum zu unverletzlichen und        
         unvera:usserlichen Menschenrechten als Grundlage jeder             
         menschlichen Gemeinschaft, des Friedens und der Gerechtigkeit in   
         der Welt.                                                          
                                                                            
      3. Die nachfolgenden Grundrechte binden Gesetzgebung, vollziehende    
         Gewalt und Rechtsprechung als unmittelbar geltendes Recht.         
                                                        --Aus dem Grundgesetz

    4.2.4.3. Tipps, Anmerkungen, Warnungen, wichtige Informationen und
    Randbemerkungen

   In bestimmten Fa:llen kann es nu:tzlich sein, dem Leser zusa:tzliche
   Informationen zu geben, die sich vom Haupttext abheben, damit der Leser
   sie besser wahrnimmt. Abha:ngig von der Art der Information, ko:nnen
   solche Stellen mit einem der Elemente tip (fu:r Tipps), note (fu:r
   Anmerkungen), warning (fu:r Warnungen), caution (fu:r besonders
   ernstzunehmende Warnungen) und important (fu:r wichtige Anmerkungen)
   ausgezeichnet werden. Trifft keines dieser Elemente fu:r die
   auszuzeichnende Stelle zu, sollte diese mit dem Element sidebar
   ausgezeichnet werden.

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

     * Eine Anmerkung (note) ist eine Information, die von jedem Leser
       beachtet werden sollte.

     * Eine wichtige Anmerkung (important) eine Variation einer Anmerkung.

     * Eine Warnung (warning) betrifft einen mo:glichen Hardwareschaden oder
       weist auf eine Gefahr fu:r Leib und Leben hin.

     * Eine besonders ernstzunehmende Warnung (caution) betrifft einen
       mo:glichen Datenverlust oder Softwareschaden.

   Beispiel 4.25. warning

 <warning>
   <para>Wenn Sie FreeBSD auf Ihrer Festplatte installieren,
     kann es sein, da&amp;szlig; Sie Windows nie mehr benutzen wollen.</para>
 </warning>

   Eine Warnung wird wie folgt dargestellt:

  Warnung:

   Wenn Sie FreeBSD auf Ihrer Festplatte installieren, kann es sein, dass Sie
   Windows nie mehr benutzen wollen.

    4.2.4.4. Listen und Handlungsanweisungen

   Listen sind ein oft gebrauchtes Hilfsmittel, wenn es darum geht,
   Informationen fu:r den Benutzer u: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 itemizedlist, orderedlist und procedure zur Verfu:gung.[13].

   itemizedlist und orderedlist a:hneln sehr stark ihren HTML-Gegenstu:cken
   ul und ol. Beide Listenarten mu:ssen mindestens ein Element listitem
   enthalten. Das listitem Element muss mindestens ein weiteres Blockelement
   enthalten.

   procedure unterscheidet sich ein wenig von den vorhergehenden. Es entha:lt
   step-Elemente, die wiederum step- oder substel-Elemente enthalten ko:nnen.
   Ein step-Element kann nur Blockelemente aufnehmen.

   Beispiel 4.26. itemizedlist, orderedlist und procedure

 <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 Aufza:hlungselement.</para>
   </listitem>

   <listitem>
     <para>Das ist das zweite Aufza: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>

   Darstellung:

     * Das ist das erste Listenelement.

     * Das ist das zweite Listenelement.

    1. Das ist das erste Aufza:hlungselement.

    2. Das ist das zweite Aufza:hlungselement.

    1. Machen Sie zuerst dies.

    2. Und dann machen Sie das..

    3. Und jetzt noch das...

    4.2.4.5. Dateiinhalte auszeichnen

   Technische Dokumente enthalten oft auch Konfigurationsbeispiele oder
   Quellcodeschnipsel. Zur Auszeichnung dieser Inhalte, stellt Docbook das
   Element programmlisting zur Verfu:gung. Im Gegensatz zu anderen
   DocBook-Elementen wird der Elementinhalt von programmlisting nicht
   normalisiert, das heisst, dass alle Leerzeichen, Tabulatoren und
   Zeilenumbru:che unvera:ndert u:bernommen werden. Aus diesem Grund ist es
   unter anderem wichtig, dass sich der o:ffende Tag in der selben Zeile wie
   der Anfang des darzustellenden Textes befindet. Gleiches gilt fu:r den
   schliessenden Tag: Er muss sich am Ende der letzten Zeile befinden. Wird
   das nicht beachtet, kann es sein, dass unerwartete Leerzeichen und
   Leerzeilen in der Ausgabe auftauchen.

   Beispiel 4.27. programlisting

 <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>

   Die spitzen Klammern der #include-Anweisung ko:nnen nicht direkt verwendet
   werden, sondern mu:ssen u:ber ihre Entita:ten eingebunden werden.

   Darstellung:

   Am Ende sollte Ihr Programm wie folgt aussehen:

 #include <stdio.h>

 int
 main(void)
 {
     printf("Hallo Welt!\n");
 }

    4.2.4.6. Textanmerkungen

   Textanmerkungen[14] sind ein Mechanismus, um auf bestimmte Stellen in
   einem vorhergehenden Beispiel oder Text zu verweisen.

   Um solche Verweise anzulegen, mu:ssen die betreffenden Stellen in den
   Beispielen (programlisting, literallayout, ...) mit co-Elementen markiert
   werden, wobei jedes Element ein eindeutiges id-Attribut besitzen muss.
   Anschliessend sollte ein calloutlist-Element eingefu:gt werden, dessen
   Elemente sich auf die co-Elemente des Beispiels beziehen und die
   jeweiligen Anmerkungen enthalten.

   Beispiel 4.28. Das co- und das calloutlist-Element

 <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 Ru: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>

   Darstellung:

   Am Ende sollte Ihr Programm wie folgt aussehen:

 #include &lt;stdio.h&gt; 1

 int 2
 main(void)
 {
     printf("Hallo Welt\n"); 3
 }

   1 Bindet die Headerdatei stdio.h ein.                                      
   2 Bestimmt den Typ des Ru:ckgabewertes von main().                         
   3 Ruft die Funktion printf() auf, die Hallo Welt! auf der Standardausgabe  
     ausgibt                                                                  

    4.2.4.7. Tabellen

   Im Gegensatz zu HTML ist es nicht notwendig, Tabellen zu Layoutzwecken
   einzusetzen, da die Layoutaufgabe von den Stylesheets u:bernommen wird.
   Stattdessen sollten Tabellen nur fu:r die Auszeichnung von Daten in
   Tabellenform genutzt werden.

   Vereinfacht betrachtet (fu: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 table-Element.
   Dieses Element selbst beinhaltet mindestens ein Element tgroup, das u:ber
   ein Attribut die Spaltenanzahl der Tabelle bestimmt. Innerhalb des
   Elementes tgroup kann sich ein Element thead mit den Spaltenu:berschriften
   und ein Element tbody mit dem eigentlichen Tabelleninhalt befinden. Beide
   Elemente beinhalten row-Elemente, die wiederum entry-Elemente beinhalten.
   Jedes entry-Element stellt eine einzelne Tabellenzelle dar.

   Beispiel 4.29. Tabellen mittels informaltable auszeichnen

 <informaltable pgwide="1">
   <tgroup cols="2">
     <thead>
       <row>
         <entry>Spaltenu:berschrift 1</entry>
         <entry>Spaltenu: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>

   Darstellung:

   +------------------------------------------------------------------------+
   |       Spaltenu:berschrift 1        |       Spaltenu:berschrift 2       |
   |------------------------------------+-----------------------------------|
   | Zeile 1, Spalte 1                  | Zeile 1, Spalte 2                 |
   |------------------------------------+-----------------------------------|
   | Zeile 2, Spalte 1                  | Zeile 2, Spalte 2                 |
   +------------------------------------------------------------------------+

   Verwenden Sie stets das Attribut pgwide mit dem Wert 1, wenn Sie das
   Element informaltable benutzen. Ein Bug des Internet Explorers verhindert
   ansonsten die korrekte Darstellung dieser Tabellen.

   Soll die Tabelle keinen Rand haben, kann das Attribut frame mit dem Wert
   none dem Element informaltable hinzugefu:gt werden (<informaltable
   frame="none">)).

   Beispiel 4.30. Tabelle mit Attribut frame="none"

   Darstellung:

           Spaltenu:berschrift 1                Spaltenu:berschrift 2         
   Zeile 1, Spalte 1                     Zeile 1, Spalte 2                    
   Zeile 2, Spalte 1                     Zeile 2, Spalte 2                    

    4.2.4.8. Beispiele fu:r den Leser

   Oft gilt es, fu: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
   erha:lt eine Antwort vom System. Ein Satz von speziellen Elementen und
   Entita:ten unterstu:tzt den Autor bei der Auszeichnung solcher
   Textstellen:

   screen

           Gedacht zur Auszeichnung von Bildschirminhalten. Im Unterschied zu
           anderen Elementen werden Leerzeichen innerhalb des Elementes
           screen unvera:ndert u:bernommen.

   prompt, &prompt.root; und &prompt.user;

           Eingabeaufforderungen des Rechners (Betriebssystem, Shell oder
           Anwendung) sind ein ha:ufig auftretender Teil dessen, was der
           Benutzer auf dem Bildschirm zu sehen bekommt. Sie sollten mit
           prompt ausgezeichnet werden.

           Ein Spezialfall sind die beiden Eingabeaufforderungen der Shell
           fu:r normale Benutzer und den Superuser root. Jedes mal wenn auf
           eine von diesen beiden Nutzerrollen hingewiesen werden soll,
           sollte entweder &prompt.root; oder &prompt.user; eingesetzt
           werden. Beide Entita:ten ko:nnen auch ausserhalb von screen
           verwendet werden.

  Anmerkung:

           &prompt.root; und &prompt.user; sind FreeBSD-spezifische
           Erweiterungen der DocBook DTD und nicht in der originalen DocBook
           DTD enthalten.

   userinput

           Das Element userinput ist fu:r die Auszeichnung von
           Benutzereingaben gedacht.

   Beispiel 4.31. screen, prompt und userinput

 <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>

   Darstellung:

 % ls -1
 foo1
 foo2
 foo3
 % ls -1 | grep foo2
 foo2
 % su
 Password:
 # cat foo2
 This is the file called 'foo2'

  Anmerkung:

   Obgleich der Inhalt der Datei foo2 in dem obigen Beispiel angezeigt wird,
   sollte dieser nicht mit programlisting ausgezeichnet werden. Vielmehr
   sollte programlisting einzig und allein fu:r die Darstellung von
   Dateifragmenten ausserhalb von Benutzeraktionen gewa:hlt werden.

  4.2.5. Flusselemente

    4.2.5.1. Hervorhebungen

   Wenn es darum geht bestimmte Wo:rter oder Textstellen hervorzuheben,
   sollte dafu:r das Element emphasis verwendet werden. Das so ausgezeichnete
   Text wird dann kursiv oder fett dargestellt; im Falle einer Sprachausgabe
   wu:rde es anders betont werden.

   Im Gegensatz zu den HTML mit seinen Elementen b und i, kennt DocBook
   keinen Weg, um diese Darstellung zu a:ndern[15]. Handelt es sich bei dem
   darzustellenden um eine wichtige Information, kann alternativ important
   verwendet werden.

   Beispiel 4.32. Das Element emphasis

 <para>FreeBSD ist zweifelslos <emphasis>das</emphasis> fu:hrende
   Unix-artige Betriebssystem fu:r die Intel-Plattform.</para>

   Darstellung:

   FreeBSD ist zweifelslos das fu:hrende Unix-artige Bestriebssystem fu:r die
   Intel-Plattform.

    4.2.5.2. Zitate

   Um einen Auszug aus einer anderen Quelle zu zitieren oder kenntlich zu
   machen, dass eine bestimmte Wendung im u:bertragenen Sinne zu verstehen
   ist, kann der betreffende Text mit Hilfe des Elementes quote ausgezeichnet
   werden. Innerhalb von quote ko:nnen die meisten der normalerweise zur
   Verfu:gung stehenden Elemente genutzt werden.

   Beispiel 4.33. Richtig zitieren

 <para>Es sollte immer sichergestellt werden, dass die Suche die Grenzen
   zwischen <quote>lokaler und o:ffentlicher Administration</quote>
   (RFC 1535) einha:lt.</para>

   Darstellung:

   Es sollte immer sichergestellt werden, das die Suche die Grenzen zwischen
   "lokaler und o:ffentlicher Administration" (RFC 1535) einha:lt.

    4.2.5.3. Tasten, Maustasten und Tastenkombinationen

   Das Element keycap beschreibt eine bestimmte Taste der Tastatur. Fu:r die
   Auszeichnung von Maustasten steht analog das Element mousebutton zur
   Verfu:gung. Mit Hilfe von keycombo ko:nnen beliebige Tasten- und
   Maustastenkombinationen beschrieben werden.

   Das Element keycombo besitzt ein Attribut action, dem einer der Werte
   click, double-click, other, press, seq oder simul zugewiesen werden kann.
   Die letzten beiden Werte deuten an, dass die genannte Kombination
   nacheinander oder gleichzeitig gedru:ckt werden soll. Die Stylesheets
   fu:gen zwischen die einzelnen Unterelemente von keycombo "+"-Zeichen ein.

   Beispiel 4.34. Tasten, Maustasten und Tastenkombinationen

   Diese Eingaben zeichnen Sie wie folgt aus:

 <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 A:nderungen zu
   speichern, muss <keycombo action="seq"><keycap>Esc</keycap>
   <keycap>:</keycap><keycap>q</keycap><keycap>!</keycap>
   </keycombo> eingegeben werden.</para>

 <para>Der Fenstermanager ist so konfiguriert, dass mittels
   <keycombo action="simul"><keycap>Alt</keycap>
   <mousebutton>rechter Maustaste</mousebutton> </keycombo>
    Fenster verschoben werden ko:nnen.</para>

   Darstellung:

   Mit der Tastenkombination Alt+F1 kann auf die zweite virtuelle Konsole
   umgeschaltet werden.

   Um vi zu beenden, ohne die A:nderungen zu speichern, muss Esc : q !
   eingegeben werden.

   Der Fenstermanager ist so konfiguriert, dass mittels Alt+rechter Maustaste
   Fenster verschoben werden ko:nnen.

    4.2.5.4. Anwendungen, Befehle, Optionen und Hilfeseiten

   Oft besteht die Notwendigkeit auf bestimmte Anwendungen und Befehle zu
   verweisen. Der Unterschied zwischen einer Anwendung und einem Befehl liegt
   darin, dass eine Anwendung ein einzelnes oder eine Gruppe von Programmen
   ist, mit denen eine bestimmte Aufgabe erledigt werden kann. Ein Befehl
   hingegen ist der Name eines Programmes, dass der Benutzer aufrufen
   kann[16].

   Desweiteren kann es auch vorkommen, dass die von einem Programm (in einem
   bestimmten Fall) akzeptierten Optionen genannt werden mu:ssen.

   Schlussendlich ist es oft gewu:nscht, zu einem Befehl dessen Abschnitt der
   Manualseiten im Unix-u:blichen Stil "Befehl(Zahl)" anzugeben.

   Anwendungsnamen ko:nnen mit application ausgezeichnet werden.

   Befehle ko:nnen zusammen mit der betreffenden Hilfeseite u:ber das
   DocBook-Element citerefentry ausgezeichnet werden. citerefentry muss zwei
   weitere Elemente enthalten: refentrytitle, fu:r den Befehlsnamen, und
   manvolnum, fu:r die Kategorie der Hilfeseite.

   Diese Art auf Befehle zu verweisen kann sehr ermu:dent sein. Daher gibt es
   einen Satz von Allgemeinen Entita:ten, der diese Arbeit erleichtert. Er
   ist in der Datei doc/share/xml/man-refs.ent enhalten und kann u:ber den
   folgenden Bezeichner eingebunden werden:

 PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

   Jede Entita:t in dieser Datei ist wie folgt aufgebaut:
   &man.Hilfeseite.Kategorie;.

   Der Anfang eines Dokumentes, das diese Entita:ten einbindet, ko:nnte so
   aussehen:

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

   Um Befehle innerhalb des Fliesstextes auszuzeichnen, kann das Element
   command genutzt werden. Die Optionen eines Befehles ko:nnen mit Hilfe von
   option ausgezeichnet werden.

   Wenn man sich mehrmals hintereinander auf den gleichen Befehl bezieht,
   sollte man beim ersten Auftreten die Notation &man.command.section;
   verwenden. Fu:r alle folgenden Referenzen sollte hingegen command
   verwendet werden. Dadurch verbessert sich das Erscheinungsbild,
   insbesondere von HTML, deutlich.

   Die Unterscheidung zwischen command und application kann schwer sein, und
   manchmal ist die Entscheidung, welches Element das richtige ist, nicht
   leicht. Das folgende Beispiel soll diese Unterscheidung erleichtern.

   Beispiel 4.35. Anwendungen, Befehle und Optionen

 <para><application>Sendmail</application> ist der verbreiteteste
   UNIX-Mailserver.</para>

 <para><application>Sendmail</application> besteht aus den Programmen
   <citerefentry>
     <refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
   </citerefentry>, &amp;man.mailq.1;, und &amp;man.newaliases.1;.</para>

 <para>Mittels der Option <option>-bp</option> kann
   <citerefentry><refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
   </citerefentry> den Status der Mailwarteschlange ausgeben.
   Der Status der Mailwarteschlange kann durch den Befehl
   <command>sendmail -bp</command> u:berpru:ft werden.</para>

   Darstellung:

   Sendmail ist der verbreitetste UNIX-Mailserver.

   Sendmail besteht aus den Programmen sendmail(8), mailq(1) sowie
   newaliases(1).

   Mittels der Option -bp kann sendmail(8) den Status der Mailwarteschlange
   ausgeben. Der Status der Mailwarteschlange kann durch den Befehl sendmail
   -bp u:berpru:ft werden.

  Anmerkung:

   Die Schreibweise &man.Hilfeseite.Kategorie; ist leichter lesbar.

    4.2.5.5. Dateien, Verzeichnisse und Erweiterungen

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

   Beispiel 4.36. Das Element filename

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

   Darstellung:

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

    4.2.5.6. Portnamen

  FreeBSD-Erweiterung:

   Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung fu:r
   DocBook und sind nicht in der originalen DocBook DTD enthalten.

   An einigen Stellen ist es notwendig, den Namen eines Ports aus FreeBSDs
   Ports-Sammlung in Dokumenten zu verwenden. In diesem Fall sollte ebenfalls
   das Element filename eingesetzt werden, dabei aber dem Element das
   Attribut role mit dem Wert package zugewiesen werden. Da die
   Ports-Sammlung an jeder beliebigen Stelle im Dateisystem installiert
   werden kann, sollte filename nur die Kategorie und den Namen des Ports
   enthalten, aber nicht das Verzeichnis /usr/ports.

   Beispiel 4.37. Portsnamen und das Element filename

 <para>Wenn Sie Ihr Netz und dessen Datenverkehr analysieren
   mo:chten, dann installieren Sie bitte den Port <filename
   role="package">net/ethereal</filename>.</para>

   Darstellung:

   Wenn Sie Ihr Netz und dessen Datenverkehr analysieren mo:chten, dann
   installieren Sie bitte den Port net/ethereal.

    4.2.5.7. Gera:tedateien unterhalb von /dev

  FreeBSD-Erweiterung:

   Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung fu:r
   DocBook und sind nicht in der originalen DocBook DTD enthalten.

   Wird in einem Dokument Bezug auf Gera:tedateien unterhalb von dev
   genommen, dann gibt es zwei Mo:glichkeiten diese auszuzeichnen. Zum einen
   kann man sich auf das Gera:t beziehen, so wie es unter /dev zu finden ist,
   und zum anderen kann man sich auf den Gera:tenamen beziehen, wie es
   innerhalb des Kerns verwendet wird. Fu:r letztere Mo:glichkeit sollte das
   Element devicename genutzt werden.

   Allerdings besteht nicht immer diese Wahlmo:glichkeit. Einige Gera:te, wie
   zum Beispiel Netzwerkkarten haben keinen Eintrag unter /dev oder werden
   anders dargestellt.

   Beispiel 4.38. Gera:tenamen per devicename auszeichnen

 <para>Unter FreeBSD wird die serielle Datenu:bertragung u:ber
   <devicename>sio</devicename> abgewickelt, das unterhalb von
   <filename>/dev</filename> eine Reihe von Eintra:gen anlegt.
   Zu diesen Eintra:gen geho:ren beispielsweise
   <filename>/dev/ttyd0</filename> und
   <filename>/dev/cuaa0</filename>.</para>

   <para>Andererseits erscheinen Gera:te wie beispielsweise
     <devicename>ed0</devicename> nicht unterhalb von
     <filename>/dev</filename>.</para>

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

   Darstellung:

   Unter FreeBSD wird die serielle Datenu:bertragung u:ber sio abgewickelt,
   das unterhalb von /dev eine Reihe von Eintra:gen anlegt. Zu diesen
   Eintra:gen beho:ren beispielsweise /dev/ttyd0 und /dev/cuaa0.

   Andererseits erscheinen Gera:te wie beispielsweise ed0 nicht unterhalb von
   /dev.

   Unter MS-DOS wird das erste Diskettelaufwerk als a: bezeichnet. FreeBSD
   bezeichnet es als /dev/fd0.

    4.2.5.8. Rechner, Domains, IP-Adressen und mehr

  FreeBSD-Erweiterung:

   Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung fu:r
   DocBook und sind nicht in der originalen DocBook DTD enthalten.

   Bezeichner fu:r Rechner ko:nnen in Abha:ngigkeit der Bezeichnungsweise auf
   verschiedene Art und Weise ausgezeichnet werden. Gemeinsam ist allen, dass
   sie das Element hostid benutzen. U:ber das Attribut role wird die Art des
   Bezeichners genauer bestimmt.

   Kein Rollenattribut oder role="hostname"

           Ohne Rollenattribut stellt der umschlossene Text einen normalen
           Rechnernamen wie freefall oder wcarchive dar. Wenn es gewu:nscht
           ist, kann mittels role="hostname" explizit angegeben werden, dass
           es sich um einen Rechnernamen handelt.

   role="domainname"

           Ein Domainname wie FreeBSD.org oder ngo.org.uk. Er entha:lt keinen
           Rechnernamen.

   role="fqdn"

           Vollqualifizierter Domainname wie www.FreeBSD.org. Entha:lt sowohl
           einen Domainnamen als auch einen Rechnernamen.

   role="ipaddr"

           Eine IP-Adresse, meistens als durch Doppelpunkte getrenntes Tupel
           von vier Zahlen dargestellt.

   role="ip6addr"

           Eine IPv6-Adresse.

   role="netmask"

           Eine Netzwerkmaske, dargestellt als ein durch Doppelpunkte
           getrenntes Vierzahlentupel, einer Hexzahl oder als ein /, dem eine
           Zahl folgt.

   role="mac"

           Eine MAC-Adresse, dargestellt durch zweistellige Hexzahlen, die
           durch Doppelpunkte getrennt sind.

   Beispiel 4.39. role und hostid

 <para>Der lokale Rechner kann immer u: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>
     geho:ren verschiedene Rechner, inklusive <hostid
     role="fqdn">freefall.FreeBSD.org</hostid> und <hostid
     role="fqdn">pointyhat.FreeBSD.org</hostid>.</para>

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

   <para>Die MAC-Adresse ist fu: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>

   Darstellung:

   Der lokale Rechner kann immer u:ber den Namen localhost angesprochen
   werden, dem immer die IP-Adresse 127.0.0.1 zugeordnet ist.

   Zur Domain FreeBSD.org geho:ren verschieden Rechner, inklusive
   freefall.FreeBSD.org und bento.FreeBSD.org.

   Wenn eine IP-Adresse einer Netzwerkkarte zugeordnet wird, was mit der
   Hilfe von ifconfig geschieht, sollte immer die Netzmaske 255.255.255.255,
   die auch hexadezimal als 0xffffffff abgegeben werden kann, benutzt werden.

   Die MAC-Adresse ist fu:r jede existierende Netzwerkkarte auf der Welt
   eindeutig. Eine typische MAC-Adresse ist beispielsweise 08:00:20:87:ef:d0.

    4.2.5.9. Benutzernamen

  FreeBSD-Erweiterung:

   Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung fu:r
   DocBook und sind nicht in der originalen DocBook DTD enthalten.

   Namen von Benutzern, wie root oder bib, ko:nnen mit dem Element username
   ausgezeichnet werden.

   Beispiel 4.40. Das Element username

 <para>Fu:r die meisten Administrationsaufgaben mu:ssen
     Sie als <username>root</username> angemeldet sein.</para>

   Darstellung:

   Fu:r die meisten Administrationsaufgaben mu:ssen Sie als root angemeldet
   sein.

    4.2.5.10. Beschreibung von Makefiles

  FreeBSD-Erweiterung:

   Die hier genannten Elemente sind Bestandteil der FreeBSD-Erweiterung fu:r
   DocBook und sind nicht in der originalen DocBook DTD enthalten.

   Zur Beschreibung von Teilen einer Makedatei stehen die beiden Elemente
   marketarget und makevar zur Verfu:gung. maketarget bezeichnet ein Ziel
   eines Makefiles, das als Parameter beim Aufruf von make angegeben werden
   kann. makevar hingegen bezeichnet eine Variable, die entweder in einem
   Makefile definiert oder make auf der Befehlszeile u:bergeben werden kann,
   um so den Bauprozess zu beeinflussen.

   Beispiel 4.41. maketarget und makevar

 <para>Zwei u:bliche Ziele in einem <filename>Makefile</filename>
   sind <maketarget>all</maketarget> und
   <maketarget>clean</maketarget>.</para>

 <para>U:blicherweise wird, wenn das Ziel <maketarget>all</maketarget>
   aufgerufen wird, die gesamte Anwendung neu erstellt. Der Aufruf
   des Zieles <maketarget>clean</maketarget> veranlasst das
   Lo:schen aller tempora:ren Dateien (zum Beispiel
   <filename>.o</filename>), die wa:hrend der U:bersetzung erzeugt
   wurden.</para>

 <para>Das genaue Verhalten von <maketarget>clean</maketarget>
   kann von einer Reihe von Variablen beeinflusst werden.
   Stellvertretend seien hier <makevar>CLOBBER</makevar> und
   <makevar>RECURSE</makevar> genannt.</para>

   Darstellung:

   Zwei u:bliche Ziele in einem Makefile sind all und clean.

   U:blicherweise wird, wenn das Ziel all aufgerufen wird, die gesamte
   Anwendung neu erstellt. Der Aufruf des Zieles clean veranlasst das
   Lo:schen aller tempora:ren Dateien (zum Beispiel .o), die wa:hrend der
   U:bersetzung erzeugt wurden.

   Das genaue Verhalten von clean kann von einer Reihe von Variablen
   beeinflusst werden. Stellvertretend seien hier CLOBBER und RECURSE
   genannt.

    4.2.5.11. Text buchstabengetreu u:bernehmen

   Fu: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
   ko:nnen soll.

   In einigen Fa:llen ist zu diesem Zwecke programlisting ausreichend, jedoch
   nicht immer. So ist programlisting zum Beispiel nicht einsetzbar, wenn es
   darum geht, einen Auszug aus einer Datei innerhalb eines Absatzes
   einzufu:gen. In solchen Fa:llen sollte das Element literal zum Einsatz
   kommen.

   Beispiel 4.42. literal

 <para>Die Zeile <literal>maxusers 10</literal> in der
   Kernelkonfigurationsdatei beeinflusst die Gro:sse vieler
   Systemtabellen und kann als ungefa:hr als Richtwert dafu:r
   gelten, wie viele parallele Anmeldungen das System handhaben
   kann.</para>

   Darstellung:

   Die Zeile maxusers 10 in der Kernelkonfigurationsdatei beeinflusst die
   Gro:sse vieler Systemtabellen und kann als ungefa:hr als Richtwert dafu:r
   gelten, wie viele paralle Anmeldungen das System handhaben kann.

    4.2.5.12. Benutzerspezifische Eingaben darstellen

   Es kommt oft vor, dass der Leser Beispiele, Dateinamen oder Kommandozeilen
   vera:ndern muss. Fu:r einen solchen Anwendungsfall ist das Element
   replaceable gedacht. Es kann innerhalb von anderen Elementen genutzt
   werden, um die Teile auszuzeichnen, die es zu ersetzen gilt.

   Beispiel 4.43. Das Element replaceable

 <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>

   Darstellung:

 % man command

   Dieses Beispiel zeigt, dass nur der Text mit replaceable umschlossen
   werden soll, den der Benutzer einzusetzen hat. Sa:mtlicher anderer Text
   sollte wie u:blich ausgezeichnet werden.

 <para>Die Zeile
   <literal>maxusers <replaceable>n</replaceable></literal>
   in der Kernelkonfigurationsdatei bestimmt die Gro:sse vieler Systemtabellen
   und stellt einen groben Richtwert dafu:r dar, wie viele gleichzeitige Anmeldungen
   das System unterstu:tzt.</para>

 <para>Fu:r einen Arbeitsplatzrechner stellt <literal>32</literal> einen guten
   Wert fu:r <replaceable>n</replaceable> dar.</para>

   Darstellung:

   Die Zeile maxusers n in der Kernelkonfigurationsdatei bestimmt die Gro:sse
   vieler Systemtabellen und stellt einen groben Richtwert dafu:r dar, wie
   viele gleichzeitige Anmeldungen das System unterstu:tzt.

   Fu:r einen Arbeitsplatzrechner stellt 32 einen guten Wert fu:r n dar.

    4.2.5.13. Fehlermeldungen des Systems darstellen

   In manchen Fa:llen kann es no:tig sein, Fehlermeldungen darzustellen, die
   von FreeBSD erzeugt werden ko:nnen. Fu:r solche Fa:lle ist das Element
   errorname vorgesehen.

   Beispiel 4.44. Das Element errorname

  <screen><errorname>Panic: cannot mount root</errorname></screen>

   Darstellung:

 Panic: cannot mount root

  4.2.6. Bilder und Grafiken

  Wichtig:

   Die Verwendung von Grafiken innerhalb der Dokumentation ist momentan noch
   in einem experimentellen Stadium. Es ist daher wahrscheinlich, dass sich
   die hier beschriebenen Mechanismen noch a:ndern werden.

   Fu:r die Verwendung von Grafiken ist es notwendig, den Port
   graphics/ImageMagick zusa:tzlich zu installieren, da er nicht vom Port
   textproc/docproj mitinstalliert wird.

   Das beste Beispiel fu:r den Einsatz von Grafiken ist der unter
   doc/en_US.ISO8859-1/articles/vm-design/ zu findene Artikel "Design
   elements of the FreeBSD VM system". 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 zusammenha:ngt. Es empfiehlt sich, den Artikel in
   verschiedenen Ausgabeformaten zu erzeugen, da man so sehen kann, wie die
   Grafiken in Abha:ngigkeit vom Ausgabemedium angeordnet werden.

    4.2.6.1. Unterstu:tze Grafikformate

   Zur Zeit werden nur zwei Grafikformate unterstu:tzt. Welches von beiden
   Formaten zum Einsatz kommen sollte, ha:ngt von der Art der Grafik ab.

   Fu:r Bilder, die vorrangig Vektorelemente wie Netzwerkdiagramme,
   Zeitlinien und a:hnliches beinhalten, sollte Encapsulated Postscript als
   Format gewa:hlt werden. Wichtig ist es in diesem Fall, dass die
   Grafikdatei die Endung .eps hat. Fu:r Bitmapgrafiken, wie zum Beispiel
   Bildschirmfotos, steht das Portable Network Grafic Format zur Verfu:gung.
   In diesem Fall, sollte die Grafikdatei immer die Endung .png haben.

   In das Subversion-Repository sollten nur Grafiken in diesen beiden
   Formaten u:bernommen werden.

   Es sollte darauf sehr darauf geachtet werden, das richtige Format fu:r das
   richtige Bild zu wa:hlen. Erwartungsgema:ss wird es Dokumente geben, die
   eine Mischung aus PNG- und EPS-Grafiken enthalten. In solchen Fa:llen,
   stellen die Makedateien die Verwendung des richtigen Formats in
   Abha:ngigkeit vom Ausgabeformat sicher. Deshalb sollte die gleiche Grafik
   niemals in zwei unterschiedlichen Formaten in das CVS-Archiv u:bernommen
   werden.

  Wichtig:

   Es ist absehbar, dass das Dokumentationsprojekt in Zukunft das Scalable
   Vector Graphic-Format (SVG) als Standardformat fu:r Vektorgrafiken
   u:bernehmen wird. Zum jetzigen Zeitpunkt ist dieser Wechsel noch nicht
   mo:glich, da der Stand der jetzigen SVG-Anwendungen noch nicht den dafu:r
   notwendigen Erfordernissen entspricht.

    4.2.6.2. DocBook-Elemente fu:r den Grafikeinsatz

   Das Auszeichnen von Bildern mittels DocBook ist relativ einfach. Zuerst
   wird ein mediaobject-Element eingefu:gt, das als Container fu:r
   medienspezifische Elemente fungieren kann. Fu:r die Zwecke des FDPs sind
   das die Elemente imageobject und textobject.

   In das mediaobject-Element sollten ein Element vom Typ imageobject und
   zwei textobject-Elemente eingefu:gt werden. Das imageobject-Element
   verweist auf die eigentliche Grafikdatei. Dabei ist allerdings nur der
   Dateipfad ohne Erweiterung anzugegeben. Die textobject-Elemente werden
   dafu:r genutzt, Texte aufzunehmen, die dem Leser anstelle des Bildes oder
   zusammen mit dem Bild angezeigt werden.

   Dies kann unter zwei Umsta:nden geschehen:

     * Wenn ein Dokument als HTML-Datei durch einem Browser angezeigt wird.
       In diesem Falle muss jeder Grafik ein Alternativtext zugeordnet
       werden, der dem Leser angezeigt werden kann. Meist ist das notwendig,
       wenn der Browser die Grafik noch nicht geladen hat oder wenn der
       Benutzer den Mauszeiger u:ber die Grafik fu:hrt.

     * Wenn das Dokument als Textdatei gelesen wird. Da in einer Textdatei
       keine Grafiken angezeigt werden ko:nnen, sollte es fu:r die Grafik
       eine Textentsprechung geben, die alternativ angezeigt werden kann.

   Das folgende Beispiel soll das bisher geschriebene illustrieren.
   Angenommen es liegt eine einzubindende Grafik in der Datei bild1.png vor,
   die die Darstellung eines As in einem Rechteck entha:lt. Die
   ASCII-Alternative ko:nnte so ausgezeichnet werden:

 <mediaobject>
   <imageobject>
     <imagedata fileref="bild1"> 1
   </imageobject>
   <textobject>
     <literallayout class="monospaced">+ - - - - - - - - - - - - - - -+ 2
 |       A       |
 +- - - - - - - - - - - - - - -+</literallayout>
   </textobject>
   <textobject>
     <phrase>Ein Bild</phrase> 3
   </textobject>
 </mediaobject>

   1 Innerhalb vom Element imageobject befindet sich ein Element imagedata,   
     welches mit Hilfe des Attributes fileref den Namen der Grafikdatei (ohne 
     Erweiterung) angibt. Die Bestimmung der Dateierweiterung wird von den    
     Stylesheets u:bernommen.                                                 
   2 Das erste textobject-Element entha:lt ein literallayout-Element, dessen  
     Attribut class den Wert monospaced zugewiesen bekommt. Der Inhalt dieses 
     Elements wird genutzt, wenn das Dokument in Textform ausgegeben wird. An 
     dieser Stelle hat der Autor die Mo:glichkeit seine "Textzeichenku:nste"  
     unter Beweis zu stellen.                                                 
                                                                              
     Wichtig ist, dass die erste und die letzte Zeile sich gleichauf mit dem  
     o:ffnenden und dem schliessenden Tag befindet. Dadurch wird              
     sichergestellt, dass keine unno:tigen Leerzeichen in die Ausgabe         
     aufgenommen werden.                                                      
   3 Das zweite textobject-Element sollte lediglich ein phrase-Element        
     enthalten. Wird das Dokument nach HTML konvertiert, wird dessen Inhalt   
     fu:r das Attribut alt des img-Tags verwendet.                            

    4.2.6.3. Die Makefile-Eintra:ge

   Alle in einem Dokument verwendeten Grafiken mu:ssen in dem zugeho:rigen
   Makefile in der Variable IMAGES enthalten sein. IMAGES sollte immer die
   Namen der Quellgrafiken enthalten. Werden in einem Dokument beispielsweise
   die drei Grafiken bild1.eps, bild2.png und bild3.png referenziert, sollte
   das Makefile die folgende Zeile enthalten:

 ...
 IMAGES= bild1.eps bild2.png bild3.png
 ...

   Eine andere Mo:glichkeit wa:re:

 ...
 IMAGES=  bild1.eps
 IMAGES+= bild2.png
 IMAGES+= bild3.png
 ...

   Es kann nicht oft genug betont werden: Welche Grafikdateien fu:r das zu
   erzeugende Dokument beno:tigt werden, wird von dem Makefiles bestimmt.
   IMAGES darf nur die Originaldateien enthalten.

    4.2.6.4. Grafiken und Kapitel in Unterverzeichnissen

   Wenn Sie Ihre Dokumentation in mehrere kleine Dateien aufspalten (siehe
   Abschnitt 3.7.1, "Dateien mit Allgemeinen Entita:ten einbinden"), mu:ssen
   Sie sorgfa:ltig vorgehen.

   Angenommen es handelt sich um ein Buch, dessen drei Kapitel in separaten
   Verzeichnissen angelegt wurden (kapitel1/kapitel.xml, kapitel2/kapitel.xml
   und kapitel3/kapitel.xml). Enthalten die Kapitel Grafiken, empfiehlt es
   sich, diese in den gleichen Verzeichnisses abzulegen, wie die Kapitel
   selbst. In diesem Falle gilt es jedoch zu beachten, dass die Pfade der
   Grafikdateien in der Variable IMAGES und in den imagedata-Elementen immer
   auch den Verzeichnisnamen enthalten.

   Soll beispielsweise die Datei kapitel1/bild1.png in das in
   kapitel1/kapitel.xml enthaltene Kapitel eingebunden werden, sollte dies so
   erfolgen:

 <mediaobject>
   <imageobject>
     <imagedata fileref="kapitel1/bild1"> 1
   </imageobject>

   ...
 </mediaobject>

   1   fileref muss den Datei- und den Verzeichnisnamen enthalten.  

   Das Makefile muss dementsprechend die Zeile

 ...
 IMAGES=  kapitel1/bild1.png
 ...

   enthalten.

   Wird dies beachtet, sollte es zu keinen Problemen kommen.

  4.2.7. Querverweise

  Anmerkung:

   Querverweise sind auch Flusselemente.

    4.2.7.1. Querverweise innerhalb eines Dokumentes

   Um innerhalb eines Dokumentes Verweise anzulegen, muss angegeben werden,
   von welcher Textstelle aus wohin verwiesen werden soll.

   Jedes DocBook-Element besitzt ein Attribut id, u:ber das seinem Element
   ein eindeutiger Bezeichner zugewiesen werden kann.

   In den meisten Fa:llen werden Querverweise nur zu Kapiteln gesetzt. Die
   chaper- und sect*-Elemente sollten aus diesem Grunde ein gesetztes
   id-Attribut besitzen.

   Beispiel 4.45. chapter und section mit dem Attribut id

 <chapter id="kapitel1">
   <title>Einfu:hrung</title>

   <para>Das ist eine Einfu:hrung. Sie entha: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>

   Als Wert fu:r das Attribut id sollte immer ein selbsterkla:render
   Bezeichner gewa:hlt werden. Zudem ist es notwendig, dass dieser Bezeichner
   innerhalb des Dokumentes eindeutig ist. Im obigen Beispiel wurde der
   Bezeichner fu:r das Unterkapitel gebildet, indem der Bezeichner des
   u:bergeordneten Kapitels um den Titel des Unterkapitels erweitert wurde.
   Diese Vorgehensweise hilft sicherzustellen, dass Bezeichner eindeutig sind
   und bleiben.

   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 Fa:llen kann an der Stelle, auf die
   verwiesen werden soll, das Element anchor mit gesetztem Attribut id
   eingefu:gt werden. anchor kann selber keinen weiteren Inhalt aufnehmen.

   Beispiel 4.46. Querverweise und das Element anchor

 <para>Dieser Absatz entha:lt ein
   <anchor id="absatz1"/>Ziel fu:r Querverweise, was jedoch keine
   Auswirkung auf dessen Darstellung hat.</para>

   Zum Anlegen des eigentlichen Querverweises selbst kann eines der beiden
   Elemente xref oder link genutzt werden. Beide besitzen das Attribut
   linkend, dem der id-Wert des Verweiszieles zugewiesen wird. Ob sich das
   Ziel vor oder nach dem Verweis befindet, spielt keine Rolle.

   xref und link unterscheiden sich jedoch hinsichtlich der Art und Weise,
   auf die der Text erzeugt wird, auf dem der Querverweis liegt. Kommt xref
   zum Einsatz, hat der Autor keine Kontrolle daru:ber - der Text wird
   automatisch fu:r ihn erzeugt.

   Beispiel 4.47. Einsatz von xref

   Fu:r dieses Beispiel wird davon ausgegangen, dass sich folgendes
   Textfragment irgendwo innerhalb eines Dokumentes auftaucht, dass das
   vorherige id-Beispiel entha:lt.

 <para>Weitere Informationen gibt
   es im <xref linkend="kapitel1"/>.</para>

 <para>Genauere Informationen ko:nnen im
   <xref linkend="kapitel1-unterkapitel1"/> gefunden werden.</para>

   Der Verweistext wird automatisch von den Stylesheets erzeugt und so
   hervorgehoben, dass ersichtlich ist, dass es sich bei dem Text um einen
   Verweis handelt.

     Weitere Informationen ko:nnen in der Einfu:hrung gefunden werden.

     Genauere Informationen ko:nnen im Unterkapitel 1 gefunden werden.

   Der Text, auf dem der HTML-Link fu:r den Querverweis liegt, wurde von den
   Kapitelu:berschriften u:bernommen.

  Anmerkung:

   Das bedeutet, dass es nicht mo:glich ist, mit der Hilfe von xref einen
   Querverweis zu einer mit anchor gekennzeichneten Stelle anzulegen. Da
   anchor keinen Inhalt aufnehmen kann, ko:nnen die Stylesheets nicht
   automatisch einen Text fu:r den Verweis erzeugen.

   Mo:chte man selber den fu:r den Verweis benutzten Text bestimmen ko:nnen,
   sollte das Element link verwendet werden. Im Gegensatz zu xref kann link
   Inhalt aufnehmen, der dann fu:r den Verweis verwendet wird.

   Beispiel 4.48. link beutzen

   Fu:r dieses Beispiel wird davon ausgegangen, dass es sich in dem Dokument
   befindet, das auch das id-Beispiel entha:lt.

 <para>Weitere Informationen ko:nnen
   im <link linkend="kapitel1">ersten Kapitel</link> gefunden
   werden.</para>

 <para>Genauere Informationen ko:nnen in
   <link linkend="kapitel1-unterkapitel1">diesem</link> Kapitel
   gefunden werden.</para>

   Aus diesem SGML-Fragment wu:rden die Stylesheets folgendes generieren (der
   hervorgehobene Text deutet den erzeugten Verweis an):

     Weitere Informationen ko:nnen im ersten Kapitel gefunden werden.

     Genauere Informationen ko:nnen in diesem Kapitel gefunden werden.

  Anmerkung:

   Das letzte Beispiel ist schlecht. Es sollten niemals Wo:rter wie "dieses"
   oder "hier" als Linktext benutzt werden. Solche Wo:rter zwingen den Leser
   dazu, den Kontext des Verweises zu lesen, um zu verstehen, wohin der
   Verweis fu:hrt.

  Anmerkung:

   Mit dem Element link kann auf mit anchor gekennzeichnete Stellen im
   Dokument verwiesen werden, da der Inhalt von link als Text fu:r den
   Querverweise genutzt wird.

    4.2.7.2. Verweise auf Dokumente im WWW

   Das Anlegen von Verweisen auf externe Dokumente ist wesentlich einfacher -
   solange die URL des zu referenzierenden Dokumentes bekannt ist. Um von
   einem bestimmten Textabschnitt auf das gewu:nschte externe Dokument zu
   verweisen, muss die jeweilige Stelle mit dem Element ulink ausgezeichnet
   werden. Mittels des Attributes url 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 fu:r den Verweis u:bernommen, den der Leser aufrufen
   kann.

   Beispiel 4.49. Verweise mit ulink

 <para>Natu:rlich ist es mo:glich, anstatt diesen Text
   weiterzulesen, sofort die
   <ulink url="&url.base;/de/index.html">FreeBSD-Homepage</ulink>
   aufzurufen.<para>

   Darstellung:

   Natu:rlich ist es mo:glich, anstatt diesen Text weiterzulesen, sofort die
   FreeBSD-Homepage aufzurufen.

     ----------------------------------------------------------------------

   [11] Die englische Bezeichnung inline element wurde in Anlehnung an das
   Wort "Fliesstext" mit "Flusselement" u:bersetzt.

   [12] Einen kurzen historischen Abriss finden Sie unter
   http://www.oasis-open.org/docbook/intro.shtml#d0e41.

   [13] DocBook kennt noch andere Elemente fu:r die Auszeichnung von Listen,
   die an dieser Stelle jedoch nicht behandelt werden.

   [14] auf Englisch: callout

   [15] Anmerkung des U:bersetzers: Hier sollte man sich noch einmal ins
   Geda:chtnis rufen, dass mittels der DocBook DTD nur Inhalte ausgezeichnet
   werden und nicht das Layout bestimmt wird.

   [16] Der Befehl mozilla startet das Programm mozilla.

                             Kapitel 5. Stylesheets

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   5.1. DSSSL

   5.2. CSS

   SGML legt nicht fest, wie ein Dokument am Monitor oder auf einem Ausdruck
   dargestellt werden soll. Fu:r diese Aufgabe wurden spezielle Sprachen
   entwickelt, die Formatvorlagen (die sogenannten Stylesheets) fu:r die
   Darstellung der Inhalte definieren. Zu diesen Sprachen geho:ren
   beispielsweise DynaText, Panorama, SPICE, JSSS, FOSI, CSS, DSSSL und
   andere mehr.

   DocBook verwendet in DSSSL geschriebene Stylesheets. XHTML verwendet
   hingegen in CSS geschriebene Stylesheets.

5.1. DSSSL

   Das Documentation Project verwendet eine anpasste Version der von Norm
   Walsh entwickelten modularen DocBook-Stylesheets, die u:ber den Port
   textproc/dsssl-docbook-modular installiert werden ko:nnen.

   Die FreeBSD-Modifikationen sind hingegen nicht in der Ports-Sammlung
   enthalten, sondern befinden sich im Quellcode-Repository des Documentation
   Projects in der Datei doc/share/xml/freebsd.dsl. Diese Datei ist umfassend
   kommentiert und mit Beispielen versehen. Dadurch ko:nnen Sie einfach
   nachvollziehen, wie die urspru:nglichen Stylesheets vom FreeBSD
   Documentation Project angepasst wurden.

5.2. CSS

   Cascading Stylesheets (CSS) erlauben es, Elementen eines XHTML-Dokuments
   Formatangaben (wie Schriftart, Gro:sse, Schriftfarbe und andere mehr)
   zuzuweisen, ohne das XHTML-Dokument mit diesen Informationen zu
   u:berfrachten.

  5.2.1. Die DocBook-Dokumente

   The FreeBSD DSSSL-Stylesheets enthalten eine Referenz auf ein Stylesheet
   namens docbook.css, das sich im gleichen Verzeichnis wie die XHTML-Dateien
   befindet. Diese projektweite CSS-Datei wird automatisch von
   doc/share/misc/docbook.css kopiert und installiert, wenn DocBook-Dokumente
   nach XHTML konvertiert werden.

                   Kapitel 6. Verzeichnisstruktur unter doc/

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   6.1. doc/ als ho:chste Ebene

   6.2. Die Verzeichnisse Sprache.Kodierung/

   6.3. Dokumentenspezifische Informationen

   Der doc/-Baum ist auf eine besondere Weise organisiert. Dies gilt analog
   fu:r die Dokumente, aus denen der FDP besteht. Das Ziel dieser
   Organisation ist es, das Hinzufu:gen neuer Dokumente zu erleichtern, sowie

    1. die automatische Konvertierung der Dokumente in andere Formate einfach
       zu gestalten,

    2. die Konsistenz zwischen den verschiedenen auf diese Weise
       organisierten Dokumenten sicherzustellen, was die parallele
       Bearbeitung verschiedener Dokumente vereinfacht, sowie

    3. die Entscheidung, wo neue Dokumente innerhalb des Baumes platziert
       werden sollen, zu erleichtern.

   Zusa:tzlich wird dadurch dem Umstand Rechnung getragen, dass die
   Dokumentation in verschiedenen Sprachen und Kodierungen vorhanden sein
   kann. Es ist von grosser Bedeutung, dass die Struktur des
   Dokumentationsbaumes dabei dennoch einheitlich bleibt.

6.1. doc/ als ho:chste Ebene

   Unterhalb von doc/ existieren zwei Arten von Verzeichnissen, die jeweils
   u:ber spezifische Dateinamen und eine spezifische Bedeutung verfu:gen.

   Verzeichnis: share/
   Bedeutung: Entha:lt Dateien, die fu:r alle Sprachen und Kodierungen der
   Dokumentation gu:ltig sind. Es entha:lt weitere Unterverzeichnisse, um
   diese Informationen zu kategorisieren. So entha:lt share/mk beispielsweise
   die Dateien, die die make(1)-Infrastruktur bilden, wa:hrend sich die fu:r
   die SMGL-Unterstu:tzung no:tigen Dateien (darunter die FreeBSD DocBook
   DTD) unter share/xml befinden.
   Verzeichnis: Sprache.Kodierung/
   Bedeutung: Fu:r jede verfu:gbare Sprache und Kodierung existiert ein
   eigenes Unterverzeichnis. Beispiele dafu:r sind en_US.ISO8859-1/ oder
   zh_TW.Big5/. Zwar sind diese Verzeichnisnamen nicht gerade kurz, durch die
   vollsta:ndige Angabe von Sprache und Kodierung werden aber Probleme bei
   einer eventuellen Erweiterung der Dokumentation (etwa um eine zusa:tzliche
   Kodierung fu:r eine bereits vorhandene Sprache) vermieden. Auch eine
   eventuelle Konvertierung der Dokumentation nach Unicode ist dadurch
   problemlos mo:glich.

6.2. Die Verzeichnisse Sprache.Kodierung/

   Diese Verzeichnisse enthalten die eigentliche Dokumentation. Auf dieser
   Ebene erfolgt eine Unterteilung in drei Kategorien, die durch
   entsprechende Verzeichnisnamen gekennzeichnet werden.

   Verzeichnis: articles
   Inhalt: DocBook-formatierte Artikel (article) oder a:hnliche Dokumente.
   Meist relativ kurz und in Abschnitte aufgeteilt. Artikel sind in der Regel
   als ein einziges, grosses HTML-Dokument verfu:gbar.
   Verzeichnis: books
   Inhalt: DocBook-formatierte Bu:cher (book) oder a:hnliche Dokumente.
   Umfangreiche Dokumente, die in Kapitel aufgeteilt werden. Sind in der
   Regel sowohl als eine einzige, grosse HTML-Datei (fu:r Personen mit einer
   schnellen Internetanbindung oder fu:r einen einfachen Druck u:ber ein
   Browser) oder als eine Sammlung von vielen kleinen, miteinander verlinkten
   Dateien verfu:gbar.
   Verzeichnis: man
   Inhalt: Dient fu:r U:bersetzungen von Manualpages. Es entha:lt ein oder
   mehrere mann-Verzeichnisse, je nachdem, welche Abschnitte der Manualpages
   bereits u:bersetzt wurden.

   Nicht jedes Sprache.Kodierung-Verzeichnis entha:lt all diese
   Unterverzeichnisse. Ob ein Verzeichnis vorhanden ist, ha:ngt vielmehr
   davon ab, ob bereits ein entsprechender Teil der Dokumentation u:bersetzt
   wurde.

6.3. Dokumentenspezifische Informationen

   Dieser Abschnitt entha:lt Informationen zu einigen vom FreeBSD
   Documentation Project (FDP) verwalteten Dokumenten.

  6.3.1. Das Handbuch

    books/handbook/

   Das Handbuch wurde unter Verwendung der vom FreeBSD Project erweiterten
   DocBook-DTD geschrieben.

   Das Handbuch ist als DocBook-book organisiert. Es besteht aus mehreren
   Teilen (parts), die wiederum mehrere Kapitel (chapter) enthalten ko:nnen.
   Kapitel sind zusa:tzlich in Abschnitte (sect1) und Unterabschnitte (sect2,
   sect3 und so weiter) unterteilt.

    6.3.1.1. Physikalische Organisation

   Das Verzeichnis handbook entha:lt sowohl weitere Verzeichnisse als auch
   zahlreiche einzelne Dateien.

  Anmerkung:

   Die Organisation des Handbuchs hat sich im Laufe der Zeit gea:ndert, daher
   ko:nnten die Informationen in diesem Abschnitt eventuell nicht mehr dem
   akutellen Stand entsprechen. Haben Sie Fragen zur Organisation des
   Handbuchs, so wenden Sie sich bitte an das FreeBSD documentation project.

      6.3.1.1.1. Makefile

   Das Makefile definiert verschiedene Variablen zur Konvertierung der
   XML-Quellen in andere Formate. Ausserdem listet es die verschiedenen
   Dateien auf, aus denen das Handbuch gebaut wird. Zusa:tzlich wird die
   Standard-doc.project.mk inkludiert, die den fu:r die Konvertierung in
   andere Formate notwendigen Code bereitstellt.

      6.3.1.1.2. book.xml

   Das Hauptdokument innerhalb des Handbuchs. Neben der DOCTYPE-Deklaration
   des Handbuchs werden hier auch die Elemente aufgelistet, die die Struktur
   des Handbuchs definieren.

   book.xml verwendet Parameterentita:ten, um Dateien mit der Endung .ent zu
   laden. Diese Dateien definieren die allgemeinen Entita:ten, die innerhalb
   des Handbuchs verwendet werden.

      6.3.1.1.3. Verzeichnis/chapter.xml

   Jedes Kapitel des Handbuchs wird in einer chapter.xml genannten Datei
   gespeichert. Jedes Verzeichnis erha:lt den Namen des id-Attributs des
   chapter-Elements.

   Entha:lt eine Kapiteldatei beispielsweise die Eintra:ge

 <chapter id="kernelconfig">
 ...
 </chapter>

   so handelt es sich um die Datei chapter.xml im Verzeichnis kernelconfig.
   Im Allgemeinen entha:lt diese Datei das komplette Kapitel.

   Wird die XHTML-Version des Handbuchs gebaut, entsteht dadurch
   kernelconfig.html. Der Grund dafu:r ist allerdings der Wert des
   id-Attributs, und nicht der Name des Verzeichnisses.

   In fru:heren Versionen des Handbuchs wurden all diese Dateien im gleichen
   Verzeichnis wie die Datei book.xml gespeichert und nach dem Wert des
   id-Attributs der chapter-Elemente benannt. Durch die Verwendung von
   eigenen Verzeichnissen fu:r die verschiedenen Kapitel wurde das Handbuch
   fu:r ku:nftige Erweiterungen vorbereitet. Beispielsweise wurde es dadurch
   mo:glich, Bilder in die einzelnen Kapitel aufzunehmen. Die Bilder fu:r das
   Handbuch werden zentral im Verzeichnis share/images/books/handbook
   gespeichert. Existiert eine lokalisierte Version eines Bildes, wird diese
   hingegen gemeinsam mit dem XML-Quellcode im gleichen Verzeichnis
   gespeichert. Ein Vorteil dieser Methode ist beispielsweise die Vermeidung
   von Namenskollisionen. Ausserdem ist es u:bersichtlicher, mit mehreren
   Verzeichnissen zu arbeiten, die jeweils nur einige Dateien enthalten, als
   mit einem einzigen Verzeichnis, das eine Vielzahl von Dateien entha:lt.

   Durch dieses Vorgehen entstanden viele Verzeichnisse, die jeweils eine
   chapter.xml enhalten, beispielsweise basics/chapter.xml,
   introduction/chapter.xml oder printing/chapter.xml.

  Wichtig:

   Im Normalfall sollte ein Umstrukturierung des Handbuchs nicht dazu
   fu:hren, dass dafu:r Dateien umbenannt werden mu:ssen (es sei denn,
   einzelne Kapitel werden neu aufgenommen oder entfernt). Kapitel und
   Verzeichnisse sollten daher nicht nach ihrer Reihenfolge innerhalb des
   Handbuchs benannt werden, da sich diese Reihenfolge bei einer
   Umstrukturierung des Handbuchs a:ndern ko:nnte.

   Die Datei chapter.xml ist keine komplette XML-Datei, da unter anderem die
   Zeilen mit der DOCTYPE-Deklaration am Beginn der Datei nicht vorhanden
   sind.

   Durch diesen Umstand ist es nicht mo:glich, einzelne Dateien direkt nach
   HTML, RTF, PS oder ein anderes Format zu konvertieren. Vielmehr muss dazu
   das komplette Handbuch neu gebaut werden.

                   Kapitel 7. Die Erzeugung der Zieldokumente

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   7.1. Fu:r den Bau der FreeBSD-Dokumentation beno:tigte Werkzeuge

   7.2. Die Makefiles des Dokumentationsbaums verstehen

   7.3. Make-Includes des FreeBSD Documentation Projects

   Dieses Kapitels erkla:rt detailliert, wie der Bau der Dokumentation
   organisiert ist und wie Sie diesen Prozess beeinflussen ko:nnen.

   Nachdem Sie dieses Kapitel gelesen haben, werden Sie:

     * Wissen, wie Sie (unter Verwendung der im Kapitel SGML-Werkzeuge
       beschriebenen Tools) die FDP-Dokumentation selbst bauen ko:nnen.

     * In der Lage sein, sowohl die make-Anweisungen der fu:r jedes Dokument
       beno:tigten Makefiles als auch die Anweisungen der projektweiten
       Vorgaben der Datei doc.project.mk zu lesen und zu verstehen.

     * Den Bau der Dokumentation u:ber make-Variablen und make-Target
       anpassen ko:nnen.

7.1. Fu:r den Bau der FreeBSD-Dokumentation beno:tigte Werkzeuge

   Zusa:tzlich zu den im Kapitel XML-Werkzeuge beschriebenen Werkzeugen
   beno:tigen Sie noch folgende Programme:

     * Das wichtigste Werkzeug zum Bau der Dokumentation ist make, genauer
       Berkeley Make.

     * Der Bau von Paketen erfolgt unter FreeBSD mit pkg_create. Wenn Sie ein
       anderes Betriebssystem als FreeBSD einsetzen, mu:ssen Sie entweder
       ohne Pakete auskommen oder den Quellcode selbst kompilieren.

     * gzip dient zur Erstellung komprimierter Versionen der Dokumentation.
       Unterstu:tzt werden sowohl bzip2- als auch zip-Archive. Wollen Sie
       Pakete der Dokumentation erstellen, beno:tigen Sie auch noch tar.

     * Mit install installieren Sie in der Standardeinstellung die
       Dokumentation auf Ihrem System. Es gibt aber auch alternative Wege,
       die Dokumentation zu installieren.

7.2. Die Makefiles des Dokumentationsbaums verstehen

   Innerhalb des FreeBSD Documentation Projects gibt es drei verschiedene
   Arten von Makefiles:

     * Ein Makefile in einem Unterverzeichnis gibt Anweisungen an dessen
       Dateien und Unterverzeichnisse weiter.

     * Ein Dokument-Makefile beschreibt das Dokument, das aus dem Inhalt des
       jeweiligen Verzeichnisses gebaut werden soll.

     * Make-Includes sind der "Klebstoff", der fu:r den Bau der Dokumentation
       erforderlich ist. In der Regel heissen diese Dokumente doc.xxx.mk.

  7.2.1. Unterverzeichnis-Makefiles

   Derartige Makefiles sind in der Regel wie folgt aufgebaut:

 SUBDIR =articles
 SUBDIR+=books

 COMPAT_SYMLINK = en

 DOC_PREFIX?= ${.CURDIR}/..
 .include "${DOC_PREFIX}/share/mk/doc.project.mk"

   Die ersten vier nicht-leeren Zeilen definieren die make-Variablen SUBDIR,
   COMPAT_SYMLINK, und DOC_PREFIX.

   Die erste SUBDIR-Anweisung weist (ebenso wie die COMPAT_SYMLINK-Anweisung)
   einer Variable einen Wert zu und u:berschreibt dabei deren urspru:nglichen
   Wert.

   Die zweite SUBDIR-Anweisung zeigt, wie man den aktuellen Wert einer
   Variable erga:nzen kann. Nach der Ausfu:hrung dieser Anweisung hat die
   Variable SUBDIR den Wert articles books.

   Die Anweisung DOC_PREFIX zeigt, wie man einer Variable einen Wert zuweist
   (vorausgesetzt, die Variable ist nicht bereits definiert). Eine derartige
   Anweisung ist beispielsweise sinnvoll, wenn sich DOC_PREFIX nicht dort
   befindet, wo es vom Makefile erwartet wird. Durch das Setzen dieser
   Variable kann der korrekte Wert an das Makefile u:bergeben werden.

   Was heisst dies nun konkret? Mit den SUBDIR-Anweisungen legen Sie fest,
   welche Unterverzeichnisse beim Bau der Dokumentation eingeschlossen werden
   mu:ssen.

   COMPAT_SYMLINK wird zur Erstellung von symbolischen Links zwischen den
   jeweiligen Dokumentsprachen und deren offizieller Kodierung beno:tigt (so
   wird beispielsweise doc/en nach en_US.ISO-8859-1 verlinkt).

   DOC_PREFIX gibt den Pfad zum Wurzelverzeichnis des Quellcode-Baums des
   FreeBSD Documentation Projects an. Diese Vorgabe kann jederzeit durch
   einen eigenen Wert ersetzt werden. Bei .CURDIR handelt es sich um eine in
   make eingebaute Variable, die den Pfad des aktuellen Verzeichnisses
   entha:lt.

   Die letzte Zeile bindet doc.project.mk, die zentrale, projektweite
   make-Datei des FreeBSD Documentation Projects, in den Bau ein. Diese Datei
   entha:lt den "Klebstoff", der die diversen Variablen in Anweisungen zum
   Bau der Dokumentation konvertiert.

  7.2.2. Dokument-Makefiles

   Diese Makefiles definieren diverse make-Variablen mit Vorgaben zum Bau der
   im Verzeichnis enthaltenen Dokumentation.

   Dazu ein Beispiel:

 MAINTAINER=nik@FreeBSD.org

 DOC?= book

 FORMATS?= html-split html

 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=

 # SGML content
 SRCS=  book.xml

 DOC_PREFIX?= ${.CURDIR}/../../..

 .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"

   Die Variable MAINTAINER ist von zentraler Bedeutung. Sie legt fest, wer
   fu:r ein bestimmtes Dokument des FreeBSD Documentation Projects
   verantwortlich ist.

   DOC (ohne die Erweiterung .xml) ist der Name des Hauptdokuments des
   Verzeichnisses, in dem sich das Makefile befindet. Mit SRCS-Anweisungen
   geben Sie alle Dokumente an, aus denen das Dokument besteht. Zusa:tzlich
   binden Sie damit wichtige Dateien ein, deren A:nderung einen erneuten Bau
   der Dokumentation erforderlich macht.

   Mit FORMATS geben Sie an, in welchen Formaten die Dokumentation gebaut
   werden soll. INSTALL_COMPRESSED entha:lt die Standardvorgaben, die beim
   Bau komprimierter Pakte der Dokumentation verwendet werden sollen. Der
   Variable INSTALL_ONLY_COMPRESS (die in der Voreinstellung leer ist) wird
   nur dann ein Wert zugewiesen, wenn ausschliesslich komprimierte Pakete der
   Dokumentation erstellt werden sollen.

  Anmerkung:

   Die Zuweisung von Werten an verschiedene Variablen wurde bereits im
   Abschnitt Unterverzeichnis-Makefiles behandelt.

   Die Variable DOC_PREFIX und die verschiedenen Include-Anweisungen sollten
   Ihnen ebenfalls bereits vertraut sein.

7.3. Make-Includes des FreeBSD Documentation Projects

   Diese Dateien lassen sich am besten verstehen, indem man sich deren Inhalt
   na:her ansieht. Konkret handelt es sich dabei um folgende Dateien:

     * doc.project.mk ist die Haupt-Include-Datei, die bei Bedarf alle
       folgenden Include-Dateien entha:lt.

     * doc.subdir.mk sorgt dafu:r, dass alle beno:tigten Verzeichnisse (und
       Unterverzeichnisse) beim Bau der Dokumentation durchlaufen werden.

     * doc.install.mk definiert Variablen, die die Installation der
       Dokumentation beeinflussen.

     * doc.docbook.mk wird verwendet, wenn die Variable DOCFORMAT den Wert
       docbook hat und die Variable DOC gesetzt ist.

  7.3.1. doc.project.mk

   Diese Datei hat folgenden Aufbau:

 DOCFORMAT?=     docbook
 MAINTAINER?=    doc@FreeBSD.org

 PREFIX?=        /usr/local
 PRI_LANG?=      en_US.ISO8859-1

 .if defined(DOC)
 .if ${DOCFORMAT} == "docbook"
 .include "doc.docbook.mk"
 .endif
 .endif

 .include "doc.subdir.mk"
 .include "doc.install.mk"

    7.3.1.1. Variablen

   DOCFORMAT und MAINTAINER enthalten Standardwerte, falls ihnen u:ber das
   Dokument-Makefile keine anderen Werte zugewiesen werden.

   Bei PREFIX handelt es sich um das Pra:fix, unter dem die zum Bau der
   Dokumentation erforderlichen SGML-Werkzeuge installiert sind. In der Regel
   handelt es sich dabei um /usr/local.

   PRI_LANG sollte auf die Sprache und Kodierung eingestellt werden, die
   unter den Leser der Dokumentation am ha:ufigsten verwendet wird. Diese
   Variable hat den Standardwert "US English".

  Anmerkung:

   PRI_LANG beeinflusst in keinster Weise, welche Dokumente gebaut werden
   ko:nnen oder sollen. Diese Variable wird lediglich dazu verwendet, ha:ufig
   verwendete Dokumente in das Wurzelverzeichnis der installierten
   Dokumentation zu verlinken.

    7.3.1.2. Bedingungen

   Die Zeile .if defined(DOC) ist ein Beispiel fu:r eine make-Bedingung, die
   (analog zum Einsatz in anderen Programmen) festlegt, was geschehen soll,
   wenn eine Bedingung "wahr" oder "falsch" ist. defined ist eine Funktion,
   die zuru:ckgibt, ob die angegebene Variable existiert oder nicht.

   .if ${DOCFORMAT} == "docbook" testet, ob die Variable DOCFORMAT den Wert
   "docbook" hat. Ist dies der Fall, wird doc.docbook.mk mit in den Bau
   aufgenommen.

   Die zwei .endifs schliessen die zwei weiter oben definierten Bedingungen.

  7.3.2. doc.subdir.mk

   Den Inhalt dieser Datei hier zu beschreiben, wu:rde zu weit fu:hren. Sie
   sollten aber nach dem Lesen der vorangegangenen Abschnitte und der
   folgenden Ausfu:hrungen in der Lage sein, Inhalt und Aufgabe dieser Datei
   zu verstehen.

    7.3.2.1. Variablen

     * SUBDIR legt die Unterverzeichnisse fest, deren Inhalt beim Bau der
       Dokumentation inkludiert werden muss.

     * Mit ROOT_SYMLINKS wird der Name der Verzeichnisse angegeben, die von
       ihrer tatsa:chlichen Position aus in das Wurzelverzeichnis, unter dem
       die Dokumentation installiert wird, verlinkt werden sollen.
       Vorausgesetzt, bei der verwendeten Sprache handelt es sich um die
       prima:re Sprache (die u:ber PRI_LANG festgelegt wird).

     * COMPAT_SYMLINK wird im Abschnitt Unterverzeichnis-Makefiles
       beschrieben.

    7.3.2.2. Targets und Makros

   Abha:ngigkeiten (Dependencies) werden folgendermassen definiert: target
   abhaengigkeit1 abhaengigkeit2 .... Um target zu bauen, mu:ssen Sie zuvor
   die angegebenen Abha:ngigkeiten bauen.

   Daran anschliessend ko:nnen Anweisungen zum Bau des angegebenen Targets
   folgen, falls der Konvertierungsprozess zwischen dem Target und seinen
   Abha:ngigkeiten nicht bereits fru:her definiert wurde oder falls die
   Konvertierung nicht der Standardkonvertierungsmethode entspricht.

   Die spezielle Abha:ngigkeit .USE definiert das A:quivalent eines Makros.

 _SUBDIRUSE: .USE
 .for entry in ${SUBDIR}
         @${ECHO} "===> ${DIRPRFX}${entry}"
         @(cd ${.CURDIR}/${entry} && \
         ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
 .endfor

   In diesem Beispiel kann _SUBDIRUSE nun als Makro, welches die angegebenen
   Befehle ausfu:hrt, verwendet werden, indem es im Makefile als
   Abha:ngigkeit angegeben wird.

   Was unterscheidet dieses Makro nun von beliebigen anderen Targets? Der
   Hauptunterschied ist, dass es nach den Anweisungen der Bauprozedur, in der
   es als Abha:ngigkeit angegeben ist, ausgefu:hrt wird. Ausserdem a:ndert es
   die Variable .TARGET (die den Namen des aktuell gebauten Targets entha:lt)
   nicht.

 clean: _SUBDIRUSE
         rm -f ${CLEANFILES}

   In diesem Beispiel fu:hrt clean das Makro _SUBDIRUSE aus, nachdem es den
   Befehl rm -f ${CLEANFILES} erfolgreich ausgefu:hrt hat. Dadurch lo:scht
   clean zwar beim Wechsel in ein neues Unterverzeichnis beim Bau erstellte
   Dateien, aber nicht beim Wechsel aus einem Unterverzeichnis in ein
   u:bergeordnetes Verzeichnis.

      7.3.2.2.1. Vorhandene Targets

     * install und package arbeiten nacheinander alle Unterverzeichnisse ab
       und rufen dabei jeweils ihre realen Versionen (realinstall
       beziehungsweise realpackage) auf.

     * clean entfernt alle Dateien, die beim Bau der Dokumentation erzeugt
       wurden (dies sowohl im aktuellen Verzeichnis als auch in allen
       Unterverzeichnissen). cleandir hat die gleiche Aufgabe, wu:rde aber
       zusa:tzlich die Objekt-Verzeichnisse lo:schen (falls diese
       existieren).

    7.3.2.3. Weitere Bedingungen

     * exists gibt "wahr" zuru:ck, wenn die angegebene Datei bereits
       existiert.

     * empty gibt "wahr" zuru:ck, wenn die angegebene Variable leer ist.

     * target gibt "wahr" zuru:ck, wenn das angegebene Target noch nicht
       existiert.

    7.3.2.4. Schleifenkonstrukte in make (.for)

   .for erlaubt es, bestimmte Anweisungen fu:r jedes Element einer Variable
   zu wiederholen, indem dieser Variable in jedem Durchlauf der Schleife das
   jeweilige Element der untersuchten Liste zugewiesen wird.

 _SUBDIRUSE: .USE
 .for entry in ${SUBDIR}
         @${ECHO} "===> ${DIRPRFX}${entry}"
         @(cd ${.CURDIR}/${entry} && \
         ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
 .endfor

   Falls das Verzeichnis SUBDIR leer ist, wu:rde in unserem Beispiel keine
   Aktion erfolgen. Entha:lt das Verzeichnis hingegen ein oder mehrere
   Elemente, werden die Anweisungen zwischen .for und .endfor fu:r jedes
   Element ausgefu:hrt, wobei entry durch das jeweilige Element ersetzt
   werden wu:rde.

                            Kapitel 8. Die Webseite

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   8.1. Vorbereitung

   8.2. Die Webseiten bauen

   8.3. Installieren der Webseiten auf Ihrem Server

   8.4. Umgebungsvariablen

8.1. Vorbereitung

   Sorgen Sie fu:r genu:gend Plattenplatz (zwischen 200 und 500 MB). Der
   genaue Wert ha:ngt davon ab, welche Methode Sie zum Bau der Webseiten
   verwenden. Dieser Platz wird von den SGML-Werkzeugen, den beno:tigten
   Teilen des Subversion-Baums, fu:r tempora:ren Speicher zum Bau der Seiten
   sowie fu:r die Installation der Webseiten beno:tigt.

  Anmerkung:

   Stellen Sie sicher, dass Ihre Dokumentationsports aktuell sind. Wenn Sie
   sich nicht sicher sind, entfernen Sie die alten Ports mit pkg_delete(1),
   bevor Sie die neue Version installieren. Derzeit wird unter anderem
   jade-1.2 vorausgesetzt. Haben Sie beispielsweise jade-1.1 installiert,
   deinstallieren Sie es mit:

 # pkg_delete jade-1.1

  8.1.1. svn verwenden

   Um Dateien aus dem doc/ Subversion-Repository "auszuchecken", muss svn
   installiert sein. Ist dies bei Ihnen noch nicht der Fall, ko:nnen Sie dies
   entweder mit pkg_add(1) oder u:ber die FreeBSD Ports-Sammlung nachholen:

 # cd /usr/ports/devel/subversion
 # make install clean

   Um alle zum Bau der Webseite beno:tigten Quellen auszuchecken, fu:hren Sie
   den folgenden Befehl aus:

 # svn checkout https://svn0.us-
 east.FreeBSD.org/doc/head/ /usr/build

   svn0.us-east.FreeBSD.org ist ein o:ffentlicher Server. Wa:hlen Sie einen
   Mirror in Ihrer Na:he und u:berpru:fen Sie das Serverzertifikat aus der
   Liste Subversion mirror sites.

  Tipp:

   Falls Sie svn nicht als Benutzer root ausfu:hren, stellen Sie bitte zuvor
   sicher, dass Sie in das Verzeichnis /usr/build schreiben du:rfen. Ist dies
   nicht mo:glich, so mu:ssen Sie hier ein anderes Zielverzeichnis angeben,
   in das die Quellen der Webseite gespeichert werden sollen.

   Nachdem svn seine Arbeit beendet hat, befindet sich die komplette
   FreeBSD-Webseite im Verzeichnis /usr/build (oder in dem von Ihnen
   angegebenen Verzeichnis). Haben Sie ein alternatives Verzeichis angegeben,
   mu:ssen Sie /usr/build in den folgenden Ausfu:hrung durch Ihr gewa:hltes
   Zielverzeichnis ersetzen.

   Das ist alles. Sie ko:nnen nun mit dem Bau der Webseiten beginnen.

8.2. Die Webseiten bauen

   Nachdem Sie die Quellen der Webseite erfolgreich heruntergeladen haben,
   ko:nnen Sie mit dem Bau der Webseite beginnen. In unserem Beispiel erfolgt
   der Bau im Verzeichnis /usr/build, in dem sich bereits alle beno:tigten
   Dateien befinden.

    1. Wechseln Sie in das Bau-Verzeichis.

 # cd /usr/build

    2. Sie starten den Bau der Webseiten, indem Sie in das Unterverzeichnis
       en_US.ISO8859-1/htdocs wechseln und dort den Befehl make(1) all
       ausfu:hren.

 # cd en_US.ISO8859-1/htdocs
 # make all

8.3. Installieren der Webseiten auf Ihrem Server

    1. Wechseln Sie wieder in das Verzeichnis en_US.ISO8859-1/htdocs, falls
       Sie dieses inzwischen verlassen haben.

 # cd /usr/build/en_US.ISO8859-1/htdocs

    2. Fu:hren Sie make(1) install aus und setzen Sie die Variable DESTDIR
       auf das Verzeichnis, in das Sie die Webseiten installieren wollen. Die
       daraus resultierenden Dateien werden unter $DESTDIR/data installiert,
       was als die document root ihres Webservers konfiguriert sein sollte.

 # env DESTDIR=/usr/local/www make install

    3. Wenn Sie die Webseiten bereits fru:her in dieses Verzeichnis
       installiert haben, wurden wa:hrend der Installation keine veralteten
       Seiten entfernt. Wenn Sie die Webseiten beispielsweise ta:glich neu
       bauen und installieren, findet und entfernt der folgende Befehl alle
       Dateien, die in den letzten drei Tagen nicht aktualisiert wurden:

 # find /usr/local/www -ctime 3 -print0 | xargs -0 rm

8.4. Umgebungsvariablen

   ENGLISH_ONLY

           Ist diese Variable gesetzt und nicht leer, bauen und installieren
           die Makefiles ausschliesslich die englischen Dokumente. Sa:mtliche
           U:bersetzungen werden dabei ignoriert. Dazu ein Beispiel:

 # make ENGLISH_ONLY=YES all install

           Wenn Sie die Variable ENGLISH_ONLY deaktivieren und alle Webseiten
           inklusive aller U:bersetzungen bauen wollen, setzen Sie die
           Variable ENGLISH_ONLY auf einen leeren Wert:

 # make ENGLISH_ONLY="" all install clean

   WEB_ONLY

           Ist diese Variable gesetzt und nicht leer, bauen und installieren
           die Makefiles nur die HTML-Seiten des Verzeichnisses
           en_US.ISO8859-1/htdocs. Alle Dokumente des Verzeichnisses
           en_US.ISO8859-1 (Handbuch, FAQ, Artikel) werden dabei ignoriert:

 # make WEB_ONLY=YES all install

   WEB_LANG

           Ist diese Variable gesetzt, wird die Dokumentation nur fu:r die
           durch diese Variable festgelegten Sprachen gebaut und im
           Verzeichnis /usr/build installiert. Alle weiteren Sprachen
           (ausgenommen Englisch) werden ignoriert. Dazu ein Beispiel:

 # make WEB_LANG="el_GR.ISO8859-7 es_ES.ISO8859-1 hu_HU.ISO8859-2 nl_NL.ISO8859-1" all install

   NOPORTSCVS

           Ist diese Variable gesetzt, checken die Makefiles keine Dateien
           aus dem Ports-CVS-Repository aus. Stattdessen werden die Dateien
           aus dem Verzeichnis /usr/ports (oder aus dem Verzeichnis, auf das
           die Variable PORTSBASE zeigt) verwendet.

   WEB_ONLY, ENGLISH_ONLY, WEB_LANG und NOPORTSCVS sind Variablen fu:r
   Makefiles. Diese werden entweder in /etc/make.conf, in Makefile.inc oder
   als Umgebungsvariablen auf der Kommandozeile oder in Ihrer
   Konfigurationsdatei gesetzt.

                           Kapitel 9. U:bersetzungen

   U:bersetzt von Johann Kois.

   Dieses Kapitel entha:lt die FAQ fu:r die U:bersetzung der FreeBSD
   Dokumentation (FAQ, Handbuch, Artikel, Manualpages und sonstige Dokumente)
   in andere Sprachen.

   Es beruht sehr stark auf den U:bersetzungs-FAQ des FreeBSD German
   Documentation Projects, die urspru:nglich von Frank Gru:nder
   <elwood@mc5sys.in-berlin.de> geschrieben und danach von Bernd Warken
   <bwarken@mayn.de> ins Englische u:bersetzt wurden.

   Diese FAQ wird vom Documentation Engineering Team <doceng@FreeBSD.org>
   gepflegt.

   9.1. Warum eine FAQ?

   9.2. Was bedeuten die Abku:rzungen i18n und l10n?

   9.3. Gibt es eigene Mailinglisten fu:r U:bersetzer?

   9.4. Werden noch U:bersetzer beno:tigt?

   9.5. Welche Sprachen muss ich dafu:r kennen/ko:nnen?

   9.6. Welche Software wird beno:tigt?

   9.7. Wie finde ich heraus, ob noch jemand Teile der Dokumentation in die
   gleiche Sprache u:bersetzt?

   9.8. Niemand u:bersetzt in meine Sprache. Was soll ich machen?

   9.9. Ich habe ein Dokument u:bersetzt. Wo soll ich es hinschicken?

   9.10. Ich arbeite als einziger an der U:bersetzung in diese Sprache, wie
   versende ich meine U:bersetzungen?

   9.11. Kann ich landes- oder sprachspezifische Informationen in meine
   U:bersetzung aufnehmen?

   9.12. Wie lassen sich sprachspezifische Zeichen darstellen?

   9.13. Wie spricht man den Leser an?

   9.14. Muss ich zusa:tzliche Informationen in meine U:bersetzungen
   einbauen?

9.1.  Warum eine FAQ?                                                                         
      Es melden sich immer mehr Leute auf der Mailingliste freebsd-doc, die Teile der FreeBSD 
      Dokumentation in andere Sprachen u:bersetzen wollen. Diese FAQ soll die am ha:ufigsten  
      gestellten Fragen beantworten, damit mo:glichst rasch mit der U:bersetzung begonnen     
      werden kann.                                                                            
9.2.  Was bedeuten die Abku:rzungen i18n und l10n?                                            
      i18n steht fu:r internationalization (Internationalisierung), l10n fu:r localization    
      (Lokalisierung). Es handelt sich dabei um besser handhabbare Abku:rzungen dieser        
      Begriffe.                                                                               
                                                                                              
      i18n kann als "i", gefolgt von 18 Buchstaben, gefolgt von einem "n", gelesen werden.    
      Analog steht l10n fu:r "l", gefolgt von 10 Buchstaben, gefolgt von einem "n".           
9.3.  Gibt es eigene Mailinglisten fu:r U:bersetzer?                                          
      Ja. Die verschiedenen U:bersetzergruppen haben jeweils eigene Mailinglisten. Genauere   
      Informationen finden Sie in der Liste der U:bersetzungsprojekte. Diese Liste entha:lt   
      die Mailinglisten und Internetseiten, die von den einzelnen U:bersetzungsprojekten      
      betrieben werden.                                                                       
9.4.  Werden noch U:bersetzer beno:tigt?                                                      
      Ja. Je mehr Leute an der U:bersetzung arbeiten, desto schneller wird diese fertig, und  
      umso schneller sind A:nderungen im englischen Original auch in den u:bersetzten         
      Dokumenten vorhanden.                                                                   
                                                                                              
      Sie mu:sssen kein professioneller Dolmetscher sein, um dabei zu helfen.                 
9.5.  Welche Sprachen muss ich dafu:r kennen/ko:nnen?                                         
      Idealerweise haben Sie gute Kenntnisse in geschriebenem Englisch, ausserdem sollten Sie 
      natu:rlich fit in der Sprache sein, in die Sie u:bersetzen wollen.                      
                                                                                              
      Englisch ist allerdings nicht unbedingt no:tig. Sie ko:nnten beispielsweise auch die    
      FAQ vom Spanischen ins Ungarische u:bersetzen.                                          
9.6.  Welche Software wird beno:tigt?                                                         
      Es ist sehr empfehlenswert, eine lokale Kopie des FreeBSD Subversion-Repository (als    
      Minimum den Dokumentationsteil) anzulegen. Dazu geben Sie den folgenden Befehl ein:     
                                                                                              
      % svn checkout https://svn0.us-east.FreeBSD.org/doc/head/ head                          
                                                                                              
        Anmerkung:                                                                            
                                                                                              
      svn0.us-east.FreeBSD.org ist ein o:ffentlicher Server. Wa:hlen Sie einen Mirror in      
      Ihrer Na:he und u:berpru:fen Sie das Serverzertifikat auf der Seite Subversion mirror   
      sites.                                                                                  
                                                                                              
        Anmerkung:                                                                            
                                                                                              
      Damit dieser Befehl funktioniert, muss der Port devel/subversion installiert sein.      
                                                                                              
      Sie sollten ausserdem mit svn vertraut sein. Damit ist es mo:glich, festzustellen, was  
      sich zwischen einzelnen Versionen eines Dokuments gea:ndert hat.                        
                                                                                              
      Wenn Sie beispielsweise wissen wollen, was sich zwischen den Revisionen r33733 und      
      r33734 der Datei en_US.ISO8859-1/books/fdp-primer/book.xml gea:ndert hat, geben Sie den 
      folgenden Befehl ein:                                                                   
                                                                                              
      % svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml                      
9.7.  Wie finde ich heraus, ob noch jemand Teile der Dokumentation in die gleiche Sprache     
      u:bersetzt?                                                                             
      Die U:bersetzungsseite des Documentation Projects listet alle U:bersetzungs-Teams auf,  
      die derzeit aktiv sind. Arbeitet bereits jemand an der U:bersetzung in Ihre Sprache, so 
      kontaktieren Sie dieses Team, damit Dokumente nicht unno:tigerweise mehrfach u:bersetzt 
      werden.                                                                                 
                                                                                              
      Wenn Ihre Sprache nicht aufgefu:hrt ist, senden Sie bitte eine E-Mail an das FreeBSD    
      documentation project. Vielleicht denkt ja jemand u:ber eine U:bersetzung nach, hat     
      sich aber noch nicht dafu:r entschieden.                                                
9.8.  Niemand u:bersetzt in meine Sprache. Was soll ich machen?                               
      Gratulation, Sie haben gerade das "FreeBSD Ihre-Sprache Documentation Translation       
      Project" gestartet. Willkommen.                                                         
                                                                                              
      Entscheiden Sie zuerst, ob Sie die dafu:r no:tige Zeit zur Verfu:gung haben. Da Sie als 
      Einziger an der U:bersetzung in Ihre Sprache arbeiten, sind Sie dafu:r verantwortlich,  
      Ihre Arbeit zu vero:ffentlichen und die Arbeit von Freiwilligen, die Ihnen dabei helfen 
      wollen, zu koordinieren.                                                                
                                                                                              
      Senden Sie eine E-Mail an die Mailingliste des Documentation Projects, in der Sie       
      bekanntgeben, dass Sie an der U:bersetzung der Dokumentation arbeiten, damit die        
      Internetseiten aktualisiert werden ko:nnen.                                             
                                                                                              
      Gibt es in Ihrem Land einen FreeBSD-Spiegelserver, so sollten Sie den dafu:r            
      Zusta:ndigen kontaktieren und nachfragen, ob er Ihnen Speicherplatz oder E-Mailadressen 
      fu:r Ihr Projekt zur Verfu:gung stellen wu:rde.                                         
                                                                                              
      Danach wa:hlen Sie ein Dokument aus und beginnen mit der U:bersetzung. Am besten        
      beginnen Sie mit kleineren Dateien, beispielsweise den FAQ oder einem der Artikel.      
9.9.  Ich habe ein Dokument u:bersetzt. Wo soll ich es hinschicken?                           
      Das kommt darauf an. Wenn Sie bereits in einem U:bersetzer-Team arbeiten (etwa dem      
      japanischen oder dem deutschen Team), dann sollten Sie deren Richtlinien zum Umgang mit 
      neuer Dokumentation folgen, die auf deren Internetseiten beschrieben werden.            
                                                                                              
      Wenn Sie die einzige Person sind, die an der U:bersetzung in eine Sprache arbeitet,     
      oder wenn Sie fu:r ein U:bersetzungsprojekt verantwortlich sind, und Ihre               
      Aktualisierungen an das FreeBSD Project u:bermitteln wollen, sollten Sie Ihre           
      U:bersetzungen dorthin senden (lesen Sie dazu auch die na:chste Frage).                 
9.10. Ich arbeite als einziger an der U:bersetzung in diese Sprache, wie versende ich meine   
      U:bersetzungen?                                                                         
                                                                                              
      oder                                                                                    
                                                                                              
      Wir sind ein U:bersetzer-Team, und wollen Dokumente versenden, die unsere Mitglieder    
      u:bersetzt haben.                                                                       
      Stellen Sie zuerst sicher, dass Ihre U:bersetzungen korrekt organisiert sind. Sie       
      sollte sich also im existierenden Dokumentationsbaum befinden, und ohne Fehler bauen    
      lassen.                                                                                 
                                                                                              
      Zurzeit wird die FreeBSD Dokumentation unterhalb des Verzeichnisses head/ gespeichert.  
      Die direkten Unterverzeichnisse werden entsprechend der Sprachkodierung benannt, in der 
      sie geschrieben sind. Diese Kodierung nach ISO639 finden Sie auf einem FreeBSD-System   
      unter /usr/share/misc/iso639, vorausgesetzt, das System wurde nach dem 20. Januar 1999  
      gebaut.                                                                                 
                                                                                              
      Wenn in Ihrer Sprache mehrere Kodierungen (wie dies etwa fu:r Chinesisch der Fall ist)  
      vorhanden sind, existiert fu:r jede Kodierung ein eigenes Unterverzeichnis.             
                                                                                              
      Zuletzt existieren auch noch Verzeichnisse fu:r die einzelnen Dokumente.                
                                                                                              
      Die Verzeichnishierarchie fu:r eine hypothetische schwedische U:bersetzung ko:nnte etwa 
      so aussehen:                                                                            
                                                                                              
      head/                                                                                   
          sv_SE.ISO8859-1/                                                                    
                           Makefile                                                           
                           htdocs/                                                            
                                 docproj/                                                     
                           books/                                                             
                                 faq/                                                         
                                     Makefile                                                 
                                     book.xml                                                 
                                                                                              
      Bei sv_SE.ISO8859-1 handelt es sich um den Namen der U:bersetzung in der lang.encoding  
      Form. Beachten Sie auch, dass zum Bauen der Dokumentation zwei Makefiles notwendig      
      sind.                                                                                   
                                                                                              
      Komprimieren Sie Ihre U:bersetzungen mit tar(1) und gzip(1) und senden Sie sie an das   
      FreeBSD Project.                                                                        
                                                                                              
      % cd doc                                                                                
      % tar cf swedish-docs.tar sv_SE.ISO8859-1                                               
      % gzip -9 swedish-docs.tar                                                              
                                                                                              
      Legen Sie das Archiv swedish-docs.tar.gz irgendwo ab. Wenn Sie keinen eigenen Webspace  
      haben (etwa weil Ihr Internetprovider Ihnen keinen zur Verfu:gung stellt), ko:nnen Sie  
      auch eine E-Mail an das Documentation Engineering Team <doceng@FreeBSD.org> schicken,   
      um abzukla:ren, ob Sie die Datei auch als E-Mail schicken ko:nnen.                      
                                                                                              
      In beiden Fa:llen sollten Sie mit send-pr(1) einen Bericht u:ber den Versand der        
      Dokumentation erstellen. Es ist sehr hilfreich, wenn Sie Ihre U:bersetzung vorher       
      korrekturlesen lassen und u:berpru:fen, da es unwahrscheinlich ist, dass der Committer  
      Ihre Sprache sehr gut beherrscht.                                                       
                                                                                              
      Danach wird jemand (meistens der Documentation Project Manager, derzeit ist dies das    
      Documentation Engineering Team <doceng@FreeBSD.org>) u:berpru:fen, ob sich Ihre         
      U:bersetzungen problemlos bauen lassen. Dabei wird besonders auf folgende Punkte        
      geachtet:                                                                               
                                                                                              
       1. Verwenden alle Dateien RCS-Strings (wie "ID")?                                      
                                                                                              
       2. Arbeitet make all im Verzeichnis sv_SE.ISO8859-1 korrekt?                           
                                                                                              
       3. Funktioniert make install ohne Probleme?                                            
                                                                                              
      Gibt es dabei Probleme, so wird die Person, die Ihren Beitrag durchsieht, sich wieder   
      an Sie wenden, damit Sie das Problem beheben.                                           
                                                                                              
      Treten keine Probleme auf, wird Ihre U:bersetzung so rasch als mo:glich committed.      
9.11. Kann ich landes- oder sprachspezifische Informationen in meine U:bersetzung aufnehmen?  
      Wir bitten Sie, dies nicht zu tun.                                                      
                                                                                              
      Nehmen wir an, dass Sie das Handbuch ins Koreanische u:bersetzen und einen Abschnitt    
      mit Ha:ndlerinformationen in das Handbuch aufnehmen wollen.                             
                                                                                              
      Es gibt keinen Grund, warum diese Information nicht auch in der englischen (oder der    
      deutschen, oder der spanischen, oder der japanischen oder der ...) Version vorhanden    
      sein sollte. Es ist etwa denkbar, dass sich jemand mit englischer Muttersprache         
      wa:hrend eines Aufenthalts in Korea eine FreeBSD-Kopie kaufen mo:chte. Ausserdem wird   
      dadurch die weltweite Pra:senz von FreeBSD verdeutlicht, was natu:rlich ebenfalls von   
      Vorteil ist.                                                                            
                                                                                              
      Wenn Sie also la:nderspezifische Informationen erga:nzen wollen, sollten Sie dies       
      zuerst in der englischen Version (mittels send-pr(1)) tun, und die A:nderung            
      anschliessend in Ihre Sprache u:bersetzen.                                              
                                                                                              
      Vielen Dank.                                                                            
9.12. Wie lassen sich sprachspezifische Zeichen darstellen?                                   
      Nicht-ASCII-Zeichen innerhalb der Dokumentation werden durch SGML-Entities dargestellt. 
                                                                                              
      Diese bestehen aus: Kaufma:nnischem Und (&), den Namen der Entity, und einem            
      Strichpunkt (;).                                                                        
                                                                                              
      Die Namen der Entities sind in ISO8879 definiert, die als Port textproc/iso8879         
      installiert werden kann.                                                                
                                                                                              
      Dazu einige Beispiele:                                                                  
                                                                                              
      Entity: &eacute;                                                                        
      Darstellung: e                                                                          
      Beschreibung: Kleines "e" mit (akutem) Akzent                                           
      Entity: &Eacute;                                                                        
      Darstellung: E                                                                          
      Beschreibung: Grosses "E" mit (akutem) Akzent                                           
      Entity: &uuml;                                                                          
      Darstellung: u:                                                                         
      Beschreibung: Kleines Umlaut-"u"                                                        
                                                                                              
      Nachdem Sie den iso8879-Port installiert haben, ist die vollsta:ndige Liste unter       
      /usr/local/share/xml/iso8879 vorhanden.                                                 
9.13. Wie spricht man den Leser an?                                                           
      In englischen Dokumenten wird der Leser mit "you" angesprochen, es wird nicht zwischen  
      formeller/informeller Anrede unterschieden, wie dies in manchen anderen Sprachen der    
      Fall ist.                                                                               
                                                                                              
      Wenn Sie in eine Sprache u:bersetzen, die diese Unterscheidung trifft, verwenden Sie    
      die Form, die auch in den anderen technischen Dokumentationen dieser Sprache verwendet  
      wird. Fu:r deutsche Versionen ist dies die dritte Person Plural ("Sie").                
9.14. Muss ich zusa:tzliche Informationen in meine U:bersetzungen einbauen?                   
      Ja.                                                                                     
                                                                                              
      Der Header der englischen Version jedes Textes sieht in etwa so aus:                    
                                                                                              
      <!--                                                                                    
           The FreeBSD Documentation Project                                                  
                                                                                              
           $FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z $     
                                                                                              
      Das exakte Aussehen kann unterschiedlich sein, die Zeile mit $FreeBSD$ sowie der        
      Ausdruck The FreeBSD Documentation Project sind allerdings immer enthalten. Beachten    
      Sie, dass die Zeile mit $FreeBSD von Subversion automatisch expandiert wird, daher      
      sollte an dieser Stelle in Ihren neuen Dokumenten nur $FreeBSD$ stehen.                 
                                                                                              
      Ihre u:bersetzten Dokumente sollten eine eigene $FreeBSD$-Zeile enthalten. Zusa:tzlich  
      sollten Sie die Zeile mit The FreeBSD Documentation Project in The FreeBSD Ihre-Sprache 
      Documentation Project a:ndern.                                                          
                                                                                              
      Ausserdem sollten Sie eine weitere Zeile einfu:gen, die festlegt, auf welcher Version   
      des englischen Originals Ihre U:bersetzung basiert.                                     
                                                                                              
      Die spanische Version dieser Datei ko:nnte etwa so beginnen:                            
                                                                                              
      <!--                                                                                    
           The FreeBSD Spanish Documentation Project                                          
                                                                                              
           $FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs $ 
           Original revision: r38674                                                          
      -->                                                                                     

                          Kapitel 10. Der Schreibstil

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   10.1. Anleitungen fu:r einen korrekten Schreibstil

   10.2. Ha:ufig verwendete Wo:rter

   Damit von verschiedenen Autoren geschriebene Dokumente zueinander
   konsistent bleiben, gibt es einige Richtlinien, denen Autoren bei der
   Erstellung ihrer Dokumente folgen mu:ssen.

   Verwendung von amerikanischem Englisch

           Es gibt mehrere englische Varianten und damit verbunden
           verschiedene Schreibweisen fu:r das gleiche Wort. Wo dies der Fall
           ist, ist die amerikanische Schreibweise zu verwenden. Man schreibt
           daher "color" statt "colour", "rationalize" statt "rationalise",
           und so weiter.

  Anmerkung:

           Die Verwendung von Britischem Englisch ist akzeptabel, wenn es
           sich um einen neuen Beitrag handelt, solange die gesamte
           Schreibweise eines Dokuments einheitlich bleibt. Alle anderen
           Dokumente wie Bu:cher, Internetseiten, Manualpages und andere
           mu:ssen allerdings amerikanisches Englisch verwenden.

   Vermeiden von Zusammenziehungen

           Verwenden Sie keine Zusammenziehungen, sondern schreiben Sie die
           Phrase immer aus. Die Schreibweise "Don't use contractions." wa:re
           also nicht korrekt.

           Die Vermeidung von Zusammenziehungen sorgt fu:r einen etwas
           formelleren Ton, ist pra:ziser und erleichtert die Arbeit der
           U:bersetzer.

   Nutzung von Kommas bei Aufza:hlungen

           Bei einer Aufza:hlung innerhalb eines Absatzes sollten Sie
           zwischen den einzelnen Begriffen Kommas setzen. Zwischen dem
           letzten und vorletzten Begriff setzen Sie ein Komma und das Wort
           "und".

           Dazu ein Beispiel:

             Das ist eine Liste von ein, zwei und drei Dingen.

           Handelt es sich dabei um eine Liste von drei Begriffen, "ein",
           "zwei", und "drei", oder um eine Liste von zwei Begriffen, "ein"
           und "zwei und drei"?

           Es ist daher besser, explizit ein serielles Komma zu setzen:

             Das ist eine Liste von ein, zwei, und drei Dingen.

   Vermeidung von redundanten Begriffen

           Versuchen Sie, keine redundanten Phrasen zu verwenden. Dies gilt
           insbesondere fu:r die Ausdru:cke "der Befehl", "die Datei", und
           "man command".

           Die folgenden zwei Beispiele veranschaulichen dies fu:r Befehle.
           Bevorzugt wird die Schreibweise des zweiten Beispiels.

           Verwenden Sie den Befehl svn, um Ihre Quellen zu aktualisieren.

           Verwenden Sie svn, um Ihre Quellen zu aktualisieren.

           Analoges gilt fu:r Dateinamen, wobei wiederum die zweite
           Schreibweise bevorzugt wird.

           ... in der Datei /etc/rc.local...

           ... in /etc/rc.local...

           Auch fu:r Manualpages gibt es zwei Schreibweisen. Auch hier wird
           die zweite Schreibweise bevorzugt (das zweite Beispiel nutzt das
           Tag citerefentry).

           Weitere Informationen finden Sie in man csh.

           Weitere Informationen finden Sie in csh(1).

   Zwei Leerzeichen am Satzende

           Verwenden Sie immer zwei Leerzeichen am Ende eines Satzes. Dadurch
           erho:ht sich die Lesbarkeit des Textes und die Nutzung von
           Werkzeugen wie Emacs wird vereinfacht.

           Nun ko:nnte man behaupten, dass ein Punkt vor einem
           Grossbuchstaben das Satzende markiert. Vor allem bei Namen,
           beispielsweise bei "Jordan K. Hubbard", ist dies allerdings nicht
           der Fall. Wir haben hier ein grosses K, gefolgt von einem Punkt
           und einem Leerzeichen. Dennoch handelt es sich nicht um den Anfang
           eines neuen Satzes.

   Eine ausfu:hrliche Beschreibung des korrekten Schreibstils finden Sie im
   Buch Elements of Style von William Strunk.

10.1. Anleitungen fu:r einen korrekten Schreibstil

   Damit die Quellen der Dokumentation selbst dann konsistent bleiben, wenn
   viele Leute daran arbeiten, folgen Sie bitte den folgenden Konventionen.

  10.1.1. Gross- und Kleinschreibung

   Tags werden in Kleinbuchstaben geschrieben, Sie schreiben also para, nicht
   PARA.

   Text im SGML-Kontext wird hingegen in Grossbuchstaben geschrieben. Man
   schreibt also <!ENTITY...> und <!DOCTYPE...>, nicht <!entity...> und
   <!doctype...>.

  10.1.2. Abku:rzungen (Akronyme)

   Abku:rzungen sollten bei ihrer ersten Verwendung immer ausgeschrieben
   werden. Man schreibt also beispielsweise "Network Time Protocol (NTP)".
   Nachdem die Abku:rzung definiert wurde, sollte hingegen nur noch die
   Abku:rzung verwendet werden, es sei denn, die Verwendung des gesamten
   Begriffes ergibt im jeweiligen Kontext mehr Sinn. Im Normalfall werden
   Akronyme in jedem Dokument nur einmal definiert. Es ist allerdings auch
   mo:glich, sie fu:r jedes Kapitel erneut zu definieren.

   Die drei ersten Vorkommen der Abku:rzung sollten in acronym-Tags
   eingeschlossen werden. Zusa:tzlich wird ein role-Attribut mit dem
   vollsta:ndigen Begriff definiert. Dadurch kann ein Link zu einem Glossar
   erzeugt werden. Ausserdem wird der komplette Begriff angezeigt, wenn man
   den Mauscursor u:ber die Abku:rzung bewegt.

  10.1.3. Einru:ckung

   Die erste Zeile jeder Datei hat die Einru:ckung 0, und zwar unabha:ngig
   von der Einru:ckung der Datei, in der sie enthalten ist.

   O:ffnende Tags erho:hen die Einru:ckung um zwei Leerzeichen. Schliessende
   Tags verringern sie hingegen um zwei Leerzeichen. Ein Block von acht
   Leerzeichen wird durch einen Tabulator ersetzt. Ein solcher Block beginnt
   immer am Anfang einer Zeile, fu:hrende Leerzeichen sind hier also nicht
   erlaubt. Vermeiden Sie ausserdem Leerzeichen am Zeilenende. Der Inhalt von
   Elementen wird um zwei Leerzeichen eingeru:ckt, wenn er sich u:ber mehr
   als eine Zeile erstreckt.

   Der Quellcode dieses Abschnitts sieht daher in etwa so aus:

 +--- Einru:ckung (Spalte) 0
 V
 <chapter>
   <title>...</title>

   <sect1>
     <title>...</title>

     <sect2>
       <title>Einru:ckung</title>

       <para>Die erste Zeile jeder Datei hat die Einru:ckung 0, und
         zwar <emphasis>unabha:ngig</emphasis> von der Einru:ckung
         der Datei, in der sie enthalten ist.</para>

       ...
     </sect2>
   </sect1>
 </chapter>

   Wenn Sie Emacs oder XEmacs verwenden, um Ihre Dateien zu bearbeiten,
   sollte der sgml-mode automatisch geladen werden, und die lokalen
   Emacs-Variablen am Ende einer Datei sollten diesen Stil erzwingen.

   Verwenden Sie Vim, sollten Sie Ihren Editor so konfigurieren:

 augroup sgmledit
   autocmd FileType sgml set formatoptions=cq2l " Special formatting options
   autocmd FileType sgml set textwidth=70       " Wrap lines at 70 columns
   autocmd FileType sgml set shiftwidth=2       " Automatically indent
   autocmd FileType sgml set softtabstop=2      " Tab key indents 2 spaces
   autocmd FileType sgml set tabstop=8          " Replace 8 spaces with a tab
   autocmd FileType sgml set autoindent         " Automatic indentation
 augroup END

  10.1.4. Die korrekte Schreibweise von Tags

    10.1.4.1. Einru:cken von Tags

   Tags, die die gleiche Einru:ckung aufweisen wie das vorangegangene Tag,
   sollten durch eine Leerzeile getrennt werden, Tags mit unterschiedlicher
   Einru:ckung hingegen nicht:

 <article lang='de'>
   <articleinfo>
     <title>NIS</title>

     <pubdate>October 1999</pubdate>

     <abstract>
       <para>...
         ...
         ...</para>
     </abstract>
   </articleinfo>

   <sect1>
     <title>...</title>

     <para>...</para>
   </sect1>

   <sect1>
     <title>...</title>

     <para>...</para>
   </sect1>
 </article>

    10.1.4.2. Gliederung von Tags

   Tags wie zum Beispiel itemizedlist, die immer weitere Tags einschliessen
   und selbst keine Zeichen enthalten, befinden sich immer in einer eigenen
   Zeile.

   Tags wie para und term ko:nnen selbst Text enthalten, und ihr Inhalt
   beginnt direkt nach dem Tag, und zwar in der gleichen Zeile.

   Dies gilt analog, wenn diese zwei Tag-Arten wieder geschlossen werden.

   Eine Vermischung dieser Tags kann daher zu Problemen fu:hren.

   Wenn auf ein Start-Tag, das keine Zeichen enthalten kann, unmittelbar ein
   Tag folgt, das andere Tags einschliessen muss, um Zeichen darzustellen,
   befinden sich diese Tags auf verschiedenen Zeilen. Das zweite Tag wird
   dabei entsprechend eingeru:ckt.

   Wenn ein Tag, das Zeichen enthalten kann, direkt nach einem Tag, das keine
   Zeichen enthalten kann, geschlossen wird, befinden sich beide Tags in der
   gleichen Zeile.

  10.1.5. Markup-A:nderungen (white space changes)

   Wenn Sie A:nderungen committen, committen Sie niemals Inhalts- und
   Formatierungsa:nderungen zur gleichen Zeit.

   Nur auf diese Weise ko:nnen die U:bersetzungs-Teams sofort erkennen,
   welche A:nderungen durch Ihren Commit verursacht wurden, ohne daru:ber
   nachdenken zu mu:ssen, ob sich der Inhalt einer Zeile oder nur deren
   Formatierung gea:ndert hat.

   Nehmen wir an, Sie haben zwei Sa:tze in einen Absatz eingefu:gt. Daher
   sind zwei Zeilen nun la:nger als 80 Zeichen. Zuerst committen Sie Ihre
   inhaltliche A:nderung inklusive der zu langen Zeilen. Im na:chsten Commit
   korrigieren Sie den Zeilenumbruch und geben in der Commit-Mitteilung an,
   dass es sich nur um A:nderung am Markup handelt (whitespace-only change),
   und U:bersetzer den Commit daher ignorieren ko:nnen.

  10.1.6. Vermeiden von fehlerhaften Zeilenumbru:chen (Nutzung von non-breaking
  space)

   Vermeiden Sie Zeilenumbru:che an Stellen, an denen diese ha:sslich
   aussehen oder es erschweren, einem Satz zu folgen. Zeilenumbru:che ha:ngen
   von der Breite des gewa:hlten Ausgabemedium ab. Insbesondere bei der
   Verwendung von Textbrowsern ko:nnen schlecht formatierte Absa:tze wie der
   folgende entstehen:

 Data capacity ranges from 40 MB to 15
 GB.  Hardware compression ...

   Die Nutzung der Entity &nbsp; verhindert Zeilenumbru:che zwischen
   zusammengeho:renden Teilen. Verwenden Sie non-breaking spaces daher in den
   folgenden Fa:llen:

     * Zwischen Zahlen und Einheiten:

 57600&nbsp;bps

     * Zwischen Programmnamen und Versionsnummern:

 FreeBSD&nbsp;4.7

     * Zwischen mehreren zusammengeho:renden Wo:rtern (Vorsicht bei Namen,
       die aus mehr als 3-4 Wo:rtern bestehen, wie "The FreeBSD Brazilian
       Portuguese Documentation Project"):

 Sun&nbsp;Microsystems

10.2. Ha:ufig verwendete Wo:rter

   Die folgende Liste entha:lt einige Beispiele, wie bestimmte Wo:rter
   innerhalb des FreeBSD Documentation Projects geschrieben werden. Finden
   Sie ein gesuchtes Wort hier nicht, sehen Sie bitte in der Liste ha:ufig
   verwendeter Wo:rter von O'Reilly nach.

     * 2.2.X

     * 4.X-STABLE

     * CD-ROM

     * DoS (Denial of Service)

     * Ports Collection

     * IPsec

     * Internet

     * MHz

     * Soft Updates

     * Unix

     * disk label

     * email

     * file system

     * manual page

     * mail server

     * name server

     * null-modem

     * web server

                        Kapitel 11. sgml-mode und Emacs

   Neuere Emacs- und XEmacs-Versionen verfu:gen u:ber ein nu:tzliches
   Lisp-Paket namens PSGML. PSGML (das u:ber den Port editors/psgml
   installiert werden kann) ist ein so genannter Majormode, der Funktionen
   speziell fu:r den Umgang mit SGML-Dateien, -Elementen und deren Attributen
   bereit stellt. Emacs aktiviert PSGML automatisch, wenn eine Datei mit der
   Endung .xml geladen oder der Befehl M-X sgml-mode eingegeben wird.

   Die Arbeit an SGML-Dokumenten wie dem FreeBSD-Handbuch kann sich
   wesentlich einfacher gestalten, wenn einige der Funktionen von PSGML
   gekannt sind:

   C-c C-e

           Ruft die Funktion sgml-insert-element auf, die nach dem Namen des
           einzufu:genden Elements fragt. Ist dieser eingegeben worden und
           wurde die Eingabetaste gedru:ckt, fu:gt die Funktion Start- und
           Endtag des neuen Elements ein. Sofern das eingefu:gte Element laut
           DTD andere Elemente enthalten muss, werden diese ebenfalls
           eingefu:gt.

           Falls Sie unsicher sind, wie der Name des gewu:nschten Elements
           lautet oder welche Elemente an der aktuellen Position erlaubt
           sind, ko:nnen mittels der Taste Tab alle an dieser Stelle
           mo:glichen Elemente angezeigt werden. Ebenso ermo:glicht Tab die
           Vervollsta:ndigung eines bereits eingegebenen Elementnamens.

   C-c =

           Ruft die Funktion sgml-change-element-name auf, mit der das
           aktuelle Element - das Element zwischen dessen Start- und Endtag
           sich der Cursor befindet - ausgewechselt werden kann. Die Funktion
           fragt nach dem Namen des neuen Elements und ersetzt anschliessend
           Start- und Endtag des alten Elements durch die des neuen Elements.

   C-c C-r

           Ruft die Funktion sgml-tag-region auf, die einen markierten
           Textabschnitt mit einem Element umschliesst. Dazu markieren Sie
           zuerst den Textabschnitt (gehen Sie zum Anfang des Abschnitts und
           fu:hren Sie C-space aus, dann gehen Sie zum Ende des Abschnitts
           und fu:hren erneut C-space aus), danach fu:hren Sie diese Funktion
           aus. Sie werden nach dem Namen des einzufu:genden Elements
           gefragt. Dessen Start-Tag wird dann am Anfang des markierten
           Textes eingefu:gt, dessen End-Tag am Ende des markierten Texts.

   C-c -

           Ruft die Funktion sgml-untag-element auf, die Start- und Endtag
           des Elements entfernt, innerhalb dessen sich der Cursor befindet.

   C-c C-q

           Ruft die Funktion sgml-fill-element auf. Diese Funktion
           formatiert[17] den Inhalt des aktuellen Elements neu. Dieser
           Vorgang betrifft auch Elemente wie programlisting, in denen
           Leerzeichen und a:hnliches Teil der Formatierung sind. Aus diesem
           Grund ist mit sgml-fill-element beda:chtig umzugehen.

   C-c C-a

           Ruft die Funktion sgml-edit-attributes auf. Diese o:ffnet einen
           zweiten Puffer mit allen Attributen des Elements, innerhalb dessen
           sich der Cursor befindet. U:ber Tab kann von einem Attribut zum
           na:chsten gewechselt werden. Ein existierender Attributwert kann
           mit C-k gelo:scht werden. Die Tastenfolge C-c C-c schliesst den
           Puffer und setzt die Attribute des Elements entsprechend den
           Puffervorgaben.

   C-c C-v

           Ruft die Funktion sgml-validate auf, die zuerst fragt, ob das
           aktuelle Dokument gespeichert werden soll und anschliessend einen
           SGML-Validator aufruft. Die Ausgaben des Validators werden in
           einem neuen Puffer angezeigt. Dadurch hat der Benutzer die
           Mo:glichkeit, eventuell vom Validator gefundene Fehler zu
           korrigieren.

   C-c /

           Startet die Funktion sgml-insert-end-tag, die automatisch das
           passende End-Tag fu:r das gerade offene Element einfu:gt.

   Zweifellos hat PSGML noch weitere nu:tzliche Funktionen, doch die hier
   genannten sind die, die der Autor dieser Fibel am meisten benutzt.

   Um den richtigen Einzug, die Umwandlung von Tabulatoren in Leerzeichen und
   die maximale Zeilenla:nge fu:r Dokumente des FDPs sicherzustellen, kann
   folgender Eintrag in .emacs vorgenommen werden:

     (defun local-sgml-mode-hook
       (setq fill-column 70
             indent-tabs-mode nil
             next-line-add-newlines nil
             standard-indent 4
             sgml-indent-data t)
       (auto-fill-mode t)
       (setq sgml-catalog-files '("/usr/local/share/xml/catalog")))
     (add-hook 'psgml-mode-hook
       '(lambda () (local-psgml-mode-hook)))

     ----------------------------------------------------------------------

   [17] Formatieren bedeutet in diesem Zusammenhang, dass die Funktion
   versucht, soviel Zeichen wie mo:glich in einer Zeile unterzubringen. Die
   Stelle, bis zu der gefu:llt und dann der Zeilemumbruch erfolgt, ist
   konfigurierbar.

                      Kapitel 12. Weiterfu:hrende Quellen

   Inhaltsverzeichnis

   12.1. Das FreeBSD-Dokumentationsprojekt

   12.2. XML

   12.3. HTML

   12.4. DocBook

   12.5. Das Linux-Dokumentationsprojekt

   In dieser Fibel werden absichtlich nicht alle Aspekte von XML, der
   erwa:hnten DTDs und des FreeBSD-Dokumentationsprojekts behandelt.
   Interessierten werden daher die nachfolgenden Quellen empfohlen.

12.1. Das FreeBSD-Dokumentationsprojekt

     * Die Webseiten des FreeBSD-Dokumentationsprojektes

     * Das FreeBSD-Handbuch

12.2. XML

     * W3C's XML-Webseite, eine umfangreiche Quelle zu XML.

12.3. HTML

     * Das World-Wide-Web-Konsortium

     * Die HTML 4.0-Spezifikation

12.4. DocBook

     * The DocBook Technical Committee, die Betreuer der DocBook-DTD.

     * DocBook: The Definitive Guide, die Online-Dokumentation zur
       DocBook-DTD.

     * The DocBook Open Repository bietet DSSSL-Stilvorlagen und andere
       Ressourcen fu:r DocBook-Benutzer an.

12.5. Das Linux-Dokumentationsprojekt

     * Die Webseiten des Linux-Dokumenationsprojektes.

                              Anhang A. Beispiele

   Inhaltsverzeichnis

   A.1. DocBook-Buch (book)

   A.2. DocBook-Artikel (article)

   A.3. Ausgabeformate erzeugen

   In diesem Anhang sind XML-Beispieldokumente und Befehle enthalten, die
   zeigen, wie man aus DocBook-Dokumenten verschiedene Ausgabeformate
   erzeugen kann. Sofern alle Werkzeuge fu:r das Dokumentationsprojekt
   ordnungsgema:ss installiert wurden, ko:nnen die angebotenen Beispiele
   direkt u:bernommen werden.

   Die Beispiele dieses Abschnitts sind bewusst einfach aufgebaut. Daher
   fehlen in den Beispielen einige Elemente, insbesondere Elemente fu:r die
   Titelei. Weitere DocBook-Beispiele ko:nnen in den DocBook-Quellen dieses
   und anderer Dokumente des FDPs gefunden werden. Die Quellen des FDPs sind
   im svn doc-Repository und online unter http://svnweb.FreeBSD.org/doc/
   verfu:gbar.

   Um Irritationen zu vermeiden, bauen die XML-Beispiele auf der 4.1er
   Standard-DocBook DTD anstatt auf der erweiterten FreeBSD-Variante auf.
   Ebenso werden die Standardstylesheets von Norman Welsh, anstatt der
   angepassten Stylesheets des FreeBSD-Dokumentationsprojektes benutzt.
   Dadurch eignen sich die Beispiele auch als generische DocBook-Vorlagen.

A.1. DocBook-Buch (book)

   Beispiel A.1. Ein DocBook-Buch (book)

 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

 <book lang='de'>
   <bookinfo>
     <title>Ein Buchbeispiel</title>

     <author>
       <firstname>Vorname</firstname>
       <surname>Nachname</surname>
       <affiliation>
         <address><email>vorname.nachname@domain.de</email></address>
       </affiliation>
     </author>

     <copyright>
       <year>2000</year>
       <holder>Urheberhinweis</holder>
     </copyright>

     <abstract>
       <para>Falls das Buch eine Zusammenfassung hat, sollte sie
         hier stehen.</para>
     </abstract>
   </bookinfo>

   <preface>
     <title>Einleitung</title>

     <para>Falls das Buch eine Einleitung hat, sollte diese hier
       stehen.</para>
   </preface>

   <chapter>
     <title>Das erste Kapitel</title>

     <para>Das ist das erste Kapitel des Buches.</para>

     <sect1>
       <title>Der erste Abschnitt</title>

       <para>Das ist der erste Abschnitte des Buches.</para>
     </sect1>
   </chapter>
 </book>

A.2. DocBook-Artikel (article)

   Beispiel A.2. Ein DocBook-Artikel (article)

 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

 <article lang='de'>
   <articleinfo>
     <title>Ein Beispielartikel</title>

     <author>
       <firstname>Vorname</firstname>
       <surname>Nachname</surname>
       <affiliation>
         <address><email>vorname.nachname@domain.de</email></address>
       </affiliation>
     </author>

     <copyright>
       <year>2000</year>
       <holder>Urheberhinweis</holder>
     </copyright>

     <abstract>
       <para>Falls der Artikel eine Zusammenfassung hat, sollte sie
         hier stehen.</programlisting>
     </abstract>
   </articleinfo>

   <sect1>
     <title>Der erste Abschnitt</title>

     <para>Das ist der erste Abschnitt des Artikels.</para>

     <sect2>
       <title>Der erste Unterabschnitt</title>

       <para>Das ist der erste Unterabschnitt des Artikels.</para>
     </sect2>
   </sect1>
 </article>

A.3. Ausgabeformate erzeugen

   Fu:r diesen Abschnitt wird vorausgesetzt, dass die im Port
   textproc/docproj enthaltene Software manuell oder u:ber das Portssystem
   installiert wurde. Weiter wird vorausgesetzt, dass alle Programme
   unterhalb des Verzeichnisses /usr/local installiert worden sind und die
   Verzeichnisse, die die ausfu:hrbaren Programme enthalten, in der Variable
   PATH enthalten sind.

  A.3.1. Benutzung von Jade

   Beispiel A.3. Ein DocBook-Dokument in eine einzelne HTML-Datei umwandeln

 % jade -V nochunks \  1
 -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ 2
 -c /usr/local/share/xml/docbook/catalog \
 -c /usr/local/share/xml/jade/catalog \
 -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \3
 -t sgml 4 datei.xml > datei.html 5

   1 U:bergibt den Parameter nochunks an die Stylesheets. Dadurch wird die    
     gesamte Ausgabe in die Standardausgabe geschrieben (bei der Benutzung    
     von Norm Walshs Stylesheets).                                            
   2 Legt die von Jade zur Verarbeitung beno:tigten drei Kataloge fest. Der   
     erste Katalog entha:lt Informationen zu den DSSSL-Stylesheets, der       
     zweite zur DocBook DTD und der dritte Jade-spezifische Informationen.    
   3 U:bergibt den vollen Pfad zum DSSSL-Stylesheet, das von Jade zur         
     Verarbeitung des Dokuments benutzt wird.                                 
   4 Weist Jade an, eine Transformation von einer DTD zu einer anderen DTD    
     vorzunehmen. In diesem Falle, von der DocBook DTD zur HTML DTD.          
   5 Legt fest, welche Datei Jade verarbeiten soll und leitet die Ausgabe in  
     die Datei datei.html um.                                                 

   Beispiel A.4. Ein DocBook-Dokument in mehrere kleine HTML-Dateien
   umwandeln

 % jade \
 -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ 1
 -c /usr/local/share/xml/docbook/catalog \
 -c /usr/local/share/xml/jade/catalog \
 -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \2
 -t sgml 3 datei.xml 4

   1 Legt die von Jade zur Verarbeitung beno:tigten drei Kataloge fest. Der   
     erste Katalog entha:lt Informationen zu den DSSSL-Stylesheets, der       
     zweite zur DocBook DTD und der dritte Jade-spezifische Informationen.    
   2 U:bergibt den vollen Pfad zum DSSSL-Stylesheet, das von Jade zur         
     Verarbeitung des Dokuments benutzt wird.                                 
   3 Weist Jade an, eine Transformation von einer DTD zu einer anderen DTD    
     vorzunehmen. In diesem Falle, von der DocBook DTD zur HTML DTD.          
   4 Legt die zu verarbeitende Datei fest. Die Stylesheets ermitteln          
     eigensta:ndig die Namen aller HTML-Ausgabedateien.                       

   Abha:ngig von der Struktur des zu verarbeitenden Dokumentes und den
   Stylesheetregeln zur Aufteilung des Dokumentes, kann dieser Befehl auch
   nur eine einzelne HTML-Datei erzeugen.

   Beispiel A.5. Ein DocBook-Dokument nach Postscript umwandeln

   Um eine Postscript-Ausgabe zu erzeugen, muss zuerst die XML-Quelle in eine
   TeX-Datei umgewandelt werden.

 % jade -V tex-backend \ 1
     -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ 2
     -c /usr/local/share/xml/docbook/catalog \
     -c /usr/local/share/xml/jade/catalog \
     -d /usr/local/share/xml/docbook/dsssl/modular/print/docbook.dsl \3
     -t tex 4 datei.xml

   1 Weist die Stylesheets an, verschiedene TeX-spezifische Optionen zu       
     benutzen.                                                                
   2 Legt die von Jade zur Verarbeitung beno:tigten drei Kataloge fest. Der   
     erste Katalog entha:lt Informationen zu den DSSSL-Stylesheets, der       
     zweite zur DocBook DTD und der dritte Jade-spezifische Informationen.    
   3 U:bergibt den vollen Pfad zum DSSSL-Stylesheet, das von Jade zur         
     Verarbeitung des Dokuments benutzt wird.                                 
   4 Weist Jade an, die Ausgabe in eine TeX-Datei umzuwandeln.                

   Die so erzeugte .tex-Datei muss anschliessend mittels tex, unter Angabe
   des Makropakets &jadetex weiterverarbeitet werden.

 % tex "&jadetex" datei.tex

   tex muss mindestens dreimal ausgefu:hrt werden. Der erste Lauf ermittelt
   die die Querverweise innerhalb des Dokumentes, die fu:r
   Stichwortverzeichnisse und a:hnliches beno:tigt werden.

   Warnungen, wie LaTeX Warning: Reference `136' on page 5 undefined on input
   line 728., die zu diesem Zeitpunkt ausgegeben werden, ko:nnen ohne
   weiteres ignoriert werden.

   Der zweite Lauf kann jetzt, da mehr Informationen, wie zum Beispiel die
   Seitenla:ngen, zur Verfu:gung stehen, Eintra:ge im Stichwortverzeichnis
   und Querverweise genauer bestimmen.

   Der dritte Lauf ist fu:r abschliessende Aufra:umarbeiten notwendig. Die so
   von tex erzeugte Ausgabe befindet sich anschliessend in der Datei
   datei.div.

   Zum Schluss muss noch dvips aufgerufen werden, um die .div-Datei in ein
   Postscript-Dokument umzuwandeln.

 % dvips -o datei.ps datei.dvi

   Beispiel A.6. Eine PDF-Datei aus einem DocBook-Dokument erzeugen

   Die ersten Schritte, um ein DocBook-Dokument in ein PDF umzuwandeln,
   stimmen mit denen u:berein, die notwendig sind, um eine Postscript-Ausgabe
   zu erzeugen (Beispiel A.5, "Ein DocBook-Dokument nach Postscript
   umwandeln").

   Nachdem die .tex-Datei durch Jade erzeugt wurde, muss pdfTeX stattdessen
   mit dem Makropaket &pdfjadetex aufgerufen werden.

 % pdftex "&pdfjadetex" datei.tex

   Dieser Befehl muss ebenfalls dreimal ausgefu:hrt werden. Am Ende liegt mit
   datei.pdf das fertige PDF-Dokument vor. Weitere Schritte sind jetzt nicht
   mehr notwendig.

                              Stichwortverzeichnis

  M

   Mitgliedschaft, U:berblick
