   Die Fibel fu:r neue Mitarbeiter des FreeBSD-Dokumentationsprojekts

   Copyright (c) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
   2006, 2007, 2008, 2009, 2010 The FreeBSD Documentation Project

   Copyright (c) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
   2006, 2007, 2008, 2009, 2010 The FreeBSD German Documentation
   Project

   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.

   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.

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

   Inhaltsverzeichnis

   Benutzungshinweise

                Die Eingabeaufforderungen

                Typographische Festlegungen

                Anmerkungen, Tips, wichtige Hinweise, Warnungen und
                Beispiel

                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.1.1. Software

                             2.1.2. Die DTDs und die Entita:ten

                             2.1.3. Die Stilvorlagen

                2.2. Optionale Werkzeuge

                             2.2.1. Software

   3. Die SGML-Fibel

                3.1. U:berblick

                3.2. Von Elementen, Tags und Attributen

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

                3.3. Die DOCTYPE-Deklaration

                             3.3.1. Formale O:ffentliche Bezeichner

                             3.3.2. Alternativen zu Formalen
                             O:ffentlichen Bezeichnern

                3.4. Die Ru:ckkehr zu SGML

                3.5. Kommentare

                             3.5.1. Fingeru:bungen...

                3.6. Entita:ten

                             3.6.1. Allgemeine Entita:ten

                             3.6.2. Parameterentita:ten

                             3.6.3. Fingeru:bungen...

                3.7. Dateien mit Entita:ten einbinden

                             3.7.1. Dateien mit Allgemeinen
                             Entita:ten einbinden

                             3.7.2. Dateien mit Parameterentita:ten
                             einbinden

                             3.7.3. Fingeru:bungen...

                3.8. Markierte Bereiche

                             3.8.1. Schlu:sselworte fu:r markierte
                             Bereiche

                             3.8.2. Fingeru:bung...

                3.9. Schlussbemerkung

   4. SGML-Dokumente erstellen

                4.1. HTML

                             4.1.1. Formale O:ffentliche Bezeichner

                             4.1.2. Die Elemente <head> und <body>

                             4.1.3. Blockelemente

                             4.1.4. Flusselemente

                             4.1.5. Links

                4.2. Die DocBook DTD

                             4.2.1. Die FreeBSD-Erweiterungen

                             4.2.2. Formelle O:ffentliche Bezeichner

                             4.2.3. Die Struktur von
                             DocBook-Dokumenten

                             4.2.4. Blockelemente

                             4.2.5. Flusselemente

                             4.2.6. Bilder und Grafiken

                             4.2.7. Querverweise

   5. Stylesheets

                5.1. DSSSL

                5.2. CSS

                             5.2.1. Die DocBook-Dokumente

   6. Verzeichnisstruktur unter doc/

                6.1. doc/ als ho:chste Ebene

                6.2. Die Verzeichnisse Sprache.Kodierung/

                6.3. Dokumentenspezifische Informationen

                             6.3.1. Das Handbuch

   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.2.1. Unterverzeichnis-Makefiles

                             7.2.2. Dokument-Makefiles

                7.3. Make-Includes des FreeBSD Documentation Projects

                             7.3.1. doc.project.mk

                             7.3.2. doc.subdir.mk

   8. Die Webseite

                8.1. Vorbereitung

                             8.1.1. Die einfache Methode: csup
                             verwenden

                             8.1.2. Die flexible Methode: Ein lokales
                             doc/www-CVS-Repository verwenden

                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.1.1. Gross- und Kleinschreibung

                             10.1.2. Abku:rzungen (Akronyme)

                             10.1.3. Einru:ckung

                             10.1.4. Die korrekte Schreibweise von
                             Tags

                             10.1.5. Markup-A:nderungen (white space
                             changes)

                             10.1.6. Vermeiden von fehlerhaften
                             Zeilenumbru:chen (Nutzung von
                             non-breaking space)

                10.2. Ha:ufig verwendete Wo:rter

   11. sgml-mode und Emacs

   12. Weiterfu:hrende Quellen

                12.1. Das FreeBSD-Dokumentationsprojekt

                12.2. SGML

                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

                             A.3.1. Benutzung von Jade

   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 HTML-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. Text mit <b> und <i> formatieren

   4-15. Nicht-proportionale Schrift mit <tt>

   4-16. Schriftgro:sse a:ndern mit <big>, <small> und <font>

   4-17. <a href="..."> benutzen

   4-18. Anwendung von <a name="...">

   4-19. Auf einen Abschnitt eines anderen Dokumentes verweisen

   4-20. Buchvorlage <book> mit <bookinfo>

   4-21. Artikelvorlage <article> mit <articleinfo>

   4-22. Ein einfaches Kapitel

   4-23. Ein leeres Kapitel

   4-24. Unterkapitel

   4-25. Absatz mit <para>

   4-26. <blockquote>

   4-27. <warning>

   4-28. <itemizedlist>, <orderedlist> und <procedure>

   4-29. <programlisting>

   4-30. Das <co>- und das <calloutlist>-Element

   4-31. Tabellen mittels <informaltable> auszeichnen

   4-32. Tabelle mit Attribut frame="none"

   4-33. <screen>, <prompt> und <userinput>

   4-34. Das Element <emphasis>

   4-35. Richtig zitieren

   4-36. Tasten, Maustasten und Tastenkombinationen

   4-37. Anwendungen, Befehle und Optionen

   4-38. Das Element <filename>

   4-39. Portsnamen und das Element <filename>

   4-40. Gera:tenamen per <devicename> auszeichnen

   4-41. role und <hostid>

   4-42. Das Element <username>

   4-43. <maketarget> und <makevar>

   4-44. <literal>

   4-45. Das Element <replaceable>

   4-46. Das Element <errorname>

   4-47. <chapter> und <section> mit dem Attribut id

   4-48. Querverweise und das Element <anchor>

   4-49. Einsatz von <xref>

   4-50. <link> beutzen

   4-51. 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

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                        #                                 

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

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 die Datei       
                                       .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 durch existierende Namen,       Dateien ko:nnen Sie mit dem    
   Dateien oder Variablen ersetzt      Befehl rm Dateiname lo:schen.
   werden mu:ssen                      
   Umgebungsvariablen                  $HOME ist Ihr                  
                                       Benutzerverzeichnis.           

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

Anmerkungen, Tips, 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.

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

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

   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 Opensourceprojekt, 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:

   Hilfeseiten

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

           Fu:r die U:bersetzung der Hilfeseiten 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
           Maillinglisten 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.

   Jede dieser vier Kategorien wird im FreeBSD-CVS-Baum verwaltet.
   Das bedeutet, dass alle A:nderungen an den Dateien fu:r jeden
   verfu:gbar sind und jeder sich mittels eines Programms wie CVSup
   oder CTM 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
   CVS-Archiv verwaltet, sofern der Autor dem zugestimmt hat. In
   anderen Fa:llen hat sich der Autor entschlossen, seine
   Dokumentation ausserhalb des zentralen FreeBSD-CVS-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 Kopie der FreeBSD-Dokumentation entweder auf
       Basis des FreeBSD-CVS-Archivs mittels CVS, CTM oder CVSup
       angelegt und gepflegt wird, oder wie mit CVSup eine frische
       Kopie des CVS-Archivs heruntergeladen wird.

     * 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. Anschliessend sollte eine lokale Kopie des
       FreeBSD-doc-Verzeichnisbaumes angelegt werden. Hierfu:r kann
       man entweder auf CVSup im checkout-Modus zuru:ckgreifen oder
       mittels cvs eine komplette Kopie des CVS-Archivs anlegen.

       Wenn man lieber mit einer Kopie des CVS-Archivs arbeiten
       mo:chte, werden als Minimum die Verzeichnisse doc/share und
       doc/de_DE.ISO8859-1/share beno:tigt.

 % cvs checkout doc/share
 % cvs checkout doc/de_DE.ISO8859-1/share

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

 % cvs checkout doc

    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:

 % cvs checkout doc/de_DE.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 doc/de_DE.ISO8859-1/articles
 % cp -R committers-guide vpn-w2k

       Bereits exisitierende 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
       doc/de_DE.ISO8859-1/books/faq:

 % cvs checkout doc/de_DE.ISO8859-1/books/faq

    4. Jetzt ko:nnen die .sgml 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 doc/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

   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 seperat 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 SGML-Fibel

   Die Mehrzahl der Dokumente des FDPs sind in SGML geschrieben. Ziel
   dieses Kapitels ist es, genau zu erkla:ren, was das bedeutet und
   wie man die SGML-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
   machinenlesbaren 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 <citerefentry/<refentrytitle/rm/<manvolnum/1//.</para>

 <screen><prompt>%</prompt> <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-Auszeichungssprache also.

   Genau diese Anforderung wird von der Standard Generalized Markup
   Language (SGML) erfu:llt. Mit ihrer Hilfe wurden viele andere
   Auszeichungssprachen 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/sgml
 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/sgml/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/sgml/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/sgml
 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/sgml/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES /usr/doc/de_DE.ISO8859-1/share/sgml/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.sgml 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.sgml

       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.sgml
 onsgmls:beispiel.sgml:5:4:E: character data is not allowed here
 onsgmls:beispiel.sgml: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     
       5      fu:r eine 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.                                            
       Bemerkungen:
       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-Kommitee. 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-Kommitee 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/sgml/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/sgml/docbook/4.1/catalog

     * /usr/local/share/sgml/html/catalog

     * /usr/local/share/sgml/iso8879/catalog

     * /usr/local/share/sgml/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 des 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 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 -->

 <!-- Ein anderer Kommentar    -->

 <!-- 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.sgml 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">

 <!-- %param.neu ist jetzt "etwas mehr Text" -->
 ]>

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

  3.6.3. Fingeru:bungen...

    1. Fu:gen Sie in beispiel.sgml 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: &version;</p>
   </body>
 </html>

    2. Validieren Sie diese Datei mit onsgmls

    3. O:ffnen Sie nun beispiel.sgml 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.sgml > 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.sgml > 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.sgml, kapitel2.sgml
   usw.) abgelegt und u:ber eine Datei buch.sgml 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.sgml">
 <!ENTITY kapitel.2 SYSTEM "kapitel2.sgml">
 <!ENTITY kapitel.3 SYSTEM "kapitel3.sgml">
 <!-- Und so weiter... -->
 ]>

 <html>
   <!-- Jetzt werden die Kapitel u:ber die Entita:ten eingebunden -->

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

     Warnung: Wenn man Allgemeine Entita:ten benutzt, um andere
     Dateien einzubinden, du:rfen diese Dateien (kapitel1.sgml,
     kapitel2.sgml, ...) 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.sgml">
 <!ENTITY kapitel.2 SYSTEM "kapitel2.sgml">
 <!ENTITY kapitel.3 SYSTEM "kapitel3.sgml">

   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" [
 <!-- Definieren einer Parameterentita:t um die Allgemeinen Entita:ten fu:r -->
 <!-- die Kapitel laden zu ko:nnen                                        -->
 <!ENTITY % kapitel SYSTEM "kapitel.ent">

 <!-- Nun wird der Inhalt der referenzierten Datei geladen -->
 %kapitel;
 ]>

 <html>
   &kapitel.1;
   &kapitel.2;
   &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.sgml, absatz2.sgml und
       absatz3.sgml) mit jeweils einer Zeile wie

 <p>Erster Absatz.</p>

       an.

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

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

 <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.sgml normalisieren:

 % osgmlnorm -d beispiel.sgml > beispiel.html

    4. O:ffnen Sie beispiel.html nun mit einem Webbrowser und
       vergewissern Sie sich, dass der Inhalt der Dateien
       absatzN.sgml 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.sgml so ab, dass es wie folgt aussieht:

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % entitaeten SYSTEM "entitaeten.sgml"> %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.sgml an, die folgenden
       Inhalt hat:

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

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

 % osgmlnorm -d beispiel.sgml > beispiel.html

    4. O:ffnen Sie beispiel.html nun mit einem Webbrowser und
       vergewissern Sie sich, dass der Inhalt der Dateien
       absatzN.sgml 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 Entit&auml;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.sgml 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.

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

                  Kapitel 4. SGML-Dokumente erstellen

   In diesem Kapitel werden die beiden vom FDP eingesetzen
   Auszeichnungssprachen HTML 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. HTML

   HTML, die HyperText Markup Language, ist die Auszeichnungssprache
   des Internets. Weitere Informationen zu HTML finden sich unter
   http://www.w3.org/.

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

   Die HTML-Spezifikation liegt bis jetzt in mehreren Versionen vor:
   1, 2, 3.0, 3.2 und (die aktuelle) 4.0. Von letzterer existieren
   zwei Varianten: "streng" (HTML 4.0 Strict) und "locker" (HTML 4.0
   Transitional).

   Die HTML-DTDs sind u:ber den Port textproc/html verfu:gbar und
   werden automatisch als Teil des Metaports textproc/docproj
   mitinstalliert.

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

  4.1.1. Formale O:ffentliche Bezeichner

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

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

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

  4.1.2. Die Elemente <head> und <body>

   Ein HTML-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 HTML-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 HTML-Dokumentes

 <html>
   <head>
     <title>Der Dokumententitel</title>
   </head>

   <body>

     ...

   </body>
 </html>

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

  4.1.3. Blockelemente

    4.1.3.1. U:berschriften

   HTML 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 HTML-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 HTML 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 enhalten.</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

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

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

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

   HTML kennt die Mo:glichkeit, dass sich eine Zelle mehrere Zeilen
   und/oder Spalten erstrecken kann. Sollen beispielsweise mehrere
   Spalten zusammenfassen werden, kann dies mit mit Hilfe des
   Attributes 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 Tablle 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>
     <!-- Da sich die zusammengefasste Zelle u:ber zwei Zeilen
          erstreckt, befindet sich das die durch dieses <td>
          definierte Zelle ganz rechts. -->

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

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

     <td>Untere mittlere Zelle</td>

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

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

  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.

   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. Fett- und Schra:gschrift

   Da mittels HTML auch Festlegungen u:ber die Darstellung getroffen
   werden ko:nnen, gibt es die Mo:glichkeit direkt zu bestimmen, dass
   bestimmte Inhalte fett oder kursiv dargestellt werden sollen. Mit
   <b> eingefasste Inhalte werden fett und mit <i> eingefasste kursiv
   dargestellt.

   Beispiel 4-14. Text mit <b> und <i> formatieren

 <p><b>Dieses</b> Wort wird fett dargestellt,
 wa:hrend <i>dieses</i> kursiv dargestellt wird.</p>

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

    4.1.4.3. Nicht-proportionale Schrift fu:r Texte

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

   Beispiel 4-15. 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.4.4. A:nderung der Schriftgro:sse

   HTML bietet auch Mo:glichkeiten, um Einfluss auf die
   Schriftgro:sse zu nehmen, das heisst, zu bestimmen, ob die Schrift
   gro:sser oder kleiner als die Standardschrift dargestellt werden
   soll. Es gibt drei verschiedene Wege, dies zu erreichen:

    1. Mittels der Tags <big> und <small> kann die
       Darstellungsgro:sse des eingeschlossenen Textes vergro:ssert
       respektive verkleinert werden. HTML erlaubt es zudem, diese
       Tags zu verschachteln, so dass auch <big><big>Das ist
       wesentlich gro:sser.</big></big> geschrieben werden kann.

    2. Das gleiche Ergebnis kann u:ber die Zuweisung der Werte 1 und
       -1 an das Attribut <size> des Tags <font> erreicht werden.
       Diese Vorgehensweise sollte allerdings als veraltet betrachtet
       werden, da der Einsatz eines CSS hierfu:r die bessere Lo:sung
       darstellt.

    3. U:ber die Zuweisung von absoluten Werten im Bereich von 1 bis
       7 an das Attribut size des Tags <font> [12]. Diese
       Herangehensweise ist ebenfalls veraltet und sollte nicht mehr
       angewandt werden.

   Beispiel 4-16. Schriftgro:sse a:ndern mit <big>, <small> und
   <font>

   Die folgenden HTML-Schnipsel bewirken alle das gleiche:

 <p>Dieser Text ist <small>etwas kleiner</small>. Dieser
   jedoch <big>ein wenig gro:sser</big>.</p>

 <p>Dieser Text ist <font size="-1">etwas kleiner</font>. Dieser
   jedoch <font size="+1">ein wenig gro:sser</font>.</p>

 <p>Dieser Text ist <font size="2">etwas kleiner</font>. Dieser
   jedoch <font size="4">ein wenig gro:sser</font>.</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-17. <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

   HTML 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-18. Anwendung von <a name="...">

 <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-19. Auf einen Abschnitt eines anderen Dokumentes
   verweisen

   Fu:r dieses Beispiel wird davon ausgegangen, dass der mit absatz1
   gekennzeichnete Absatz sich in der HTML-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:glich von HaL Computer Systems and O'Reilly &
   Associates als DTD fu:r das Erstellen von technischen Dokumenten
   entwickelt [13]. 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 HTML.

     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 Elementeninhalt 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 mitinstalliert.

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

  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-CVS-Archiv
   (doc/share/sgml/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.1-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 ist 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-20. 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-21. 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-22. Ein einfaches Kapitel

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

   ...
 </chapter>

   Kapitel ko:nnen nicht leer sein. Nebem 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-23. 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-24. Unterkapitel

 <chapter>
   <title>Ein Beispielkapitel</title>

   <para>Ein beliebiger Text.</para>

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

     ...
   </sect1>

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

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

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

          ...
       </sect3>
     </sect2>

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

       ...
     </sect2>
   </sect1>
 </chapter>

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

      ...
   </chapter>

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

     ...
   </chapter>

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

     ...
   </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-25. 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-26. <blockquote>

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

 <blockquote>
   <title>Menschenw&uuml;rde; Grundrechtsbindung der staatlichen Gewalt</title>

   <attribution>Aus dem Grundgesetz</attribution>

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

   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 Element 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-27. <warning>

 <warning>
   <para>Wenn Sie FreeBSD auf Ihrer Festplatte installieren,
     kann es sein, da&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.[14].

   <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-28. <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...</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-29. <programlisting>

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

 <programlisting>#include &lt;stdio.h&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[15] 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-30. Das <co>- und das <calloutlist>-Element

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

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

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

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

   <callout arearefs="co-ex-return">
     <para>Bestimmt den Typ des 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-31. 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-32. 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 (Betriebssysten, 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.
           Jedesmal 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-33. <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[16]. Handelt
   es sich bei dem darzustellenden um eine wichtige Information, kann
   alternativ <important> verwendet werden.

   Beispiel 4-34. Das Element <emphasis>

 <para>FreeBSD ist zweifelslos <emphasis>das</emphasis> fu:hrende
   Unix-artige Bestriebssystem 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-35. 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-36. 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[17].

   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/sgml/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 auszuzeichen, 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-37. Anwendungen, Befehle und Optionen

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

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

 <para>Mittels der Option <option>-bp</option> kann
   <citerefentry><refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
   </citerefentry> den Status der Mailwarteschlange ausgeben.
   Der Status der Mailwarteschlange kann durch den Befehl
   <command>sendmail -bp</command> 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-38. 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.sgml</filename>. Desweiteren sollte
             sich eine Datei mit dem Namen
             <filenname>Makefile</filename> zusammen mit mehreren
             Dateien mit der Endung <filename>.ent</filename> in diesem
             Verzeichnis befinden.</para>

   Darstellung:

   Die SGML-Quellen des englischen Handbuches befinden sich im
   Verzeichnis /usr/doc/en/handbook/. In diesem Verzeichnis befindet
   sich eine Datei handbook.sgml. 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-39. 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 Netzwerkkartenm haben keinen Eintrag
   unter /dev oder werden anders dargestellt.

   Beispiel 4-40. 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 beho: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 Diskettelaufwerk 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
           normlen 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-41. 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-42. 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-43. <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-44. <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 paralle 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-45. 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-46. 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 CVS-Archiv 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 einzubindene Grafik in der Datei bild1
   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:ffenden 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), mu:ssen Sie sorgfa:ltig vorgehen.

   Angenommen es handelt sich um ein Buch, dessen drei Kapitel in
   separaten Verzeichnissen angelegt wurden (kapitel1/kapitel.sgml,
   kapitel2/kapitel.sgml und kapitel3/kapitel.sgml). 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 mitenthalten.

   Soll beispielsweise die Datei kapitel1/bild1.png in das in
   kapitel1/kapitel.sgml 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-47. <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-48. 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-49. 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-50. <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-51. Verweise mit <ulink>

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

   Darstellung:

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

   

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

                         Kapitel 5. Stylesheets

   U:bersetzt von Johann Kois.

   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. HTML
   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/sgml/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
   HTML-Dokuments Formatangaben (wie Schriftart, Gro:sse,
   Schriftfarbe und andere mehr) zuzuweisen, ohne das HTML-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 HTML-Dateien befindet. Diese projektweite CSS-Datei wird
   automatisch von doc/share/misc/docbook.css kopiert und
   installiert, wenn DocBook-Dokumente nach HTML konvertiert werden.

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

               Kapitel 6. Verzeichnisstruktur unter doc/

   U:bersetzt von Johann Kois.

   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/sgml 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 (<part>s), 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 SGML-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.sgml

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

   book.sgml 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.sgml

   Jedes Kapitel des Handbuchs wird in einer chapter.sgml 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.sgml im Verzeichnis
   kernelconfig. Im Allgemeinen entha:lt diese Datei das komplette
   Kapitel.

   Wird die HTML-Version des Handbuchs gebaut, entsteht dadurch die
   HTML-Datei 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.sgml 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 SGML-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.sgml enhalten, beispielsweise basics/chapter.sgml,
   introduction/chapter.sgml oder printing/chapter.sgml.

     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.sgml ist keine komplette SGML-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.

   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 SGML-Werkzeuge beschriebenen
   Werkzeugen beno:tigen Sie noch folgende Programme:

     * Das wichtigste Werzeug 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 zweigt, 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.sgml

 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 .sgml) 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 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 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.

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

   Sie haben zwei Mo:glichkeiten, an die fu:r den Bau der Webseiten
   no:tigen Dateien zu gelangen:

     * Sie ko:nnen csup verwenden, um eine lokale Kopie der Dateien
       von einem CVSup-Server herunterzuladen. Dies ist die
       einfachste Methode, da Sie keine zusa:tzlichen Programme
       installieren mu:ssen. Das im na:chsten Abschnitt beschriebene
       supfile la:dt jeweils die aktuellste Version der beno:tigten
       Dateien herunter. Diese Methode ist ausreichend, wenn Sie die
       Webseiten nur lokal bauen wollen, aber keine Vera:nderungen
       committen wollen.

     * Alternativ verwenden Sie cvsup im "cvs"-Modus, um ein lokales
       CVS-Repository zu erzeugen und zu verwalten. Dazu mu:ssen Sie
       zwar ein zusa:tzliches Programm (net/cvsup-without-gui)
       installieren, haben aber zusa:tzliche Mo:glichkeiten, etwa die
       Verwaltung verschiedener Revisionen der doc/www-Dateien und
       deren Historie. Ausserdem erlaubt es diese Methode Ihnen,
       Vera:nderungen in das zentrale FreeBSD-CVS-Repository zu
       committen.

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

  8.1.1. Die einfache Methode: csup verwenden

   csup ist Teil des FreeBSD-Basissystems und wird inzwischen von den
   meisten Benutzern zur Aktualisierung der Ports-Sammlung verwendet.
   Das folgende supfile kann dazu verwendet werden, um die zum Bau
   der Webseiten beno:tigten Dateien auszuchecken:

 #
 # This file checks out all collections required to rebuild
 # the FreeBSD website
 #
 # Use the nearest CVSup mirror
 # listed at http://www.freebsd.org/doc/handbook/mirrors.html.

 *default host=cvsup10.FreeBSD.org
 *default base=/var/db
 *default prefix=/usr/build
 *default release=cvs tag=.
 *default delete use-rel-suffix
 *default compress

 # This will retrieve the entire doc branch of the FreeBSD repository.

 doc-all

 # This will retrieve the files required for the website

 www

 # This will retrieve some basic ports info required for the build

 ports-base

   A:ndern Sie den Eintrag default host in einen CVSup-Spiegelserver
   in Ihrer Na:he, bevor Sie mit dem Checkout beginnen. Ausserdem
   sollten Sie den Eintrag default prefix a:ndern, wenn Sie die
   ausgecheckten Dateien an einem anderen Ort speichern wollen.
   Danach speichern Sie die Datei beispielsweise als doc-www-supfile
   ab und fu:hren den folgenden Befehl aus:

 # csup -g -L2 doc-www-supfile

   Nachdem dieser Befehl ausgefu:hrt wurde, finden Sie drei neue
   Verzeichnisse, doc/, www/ sowie ports/ im Verzeichnis, das Sie
   durch den Eintrag default prefix (in unserem Beispiel /usr/build)
   festgelegt haben. Wir werden das gleiche Verzeichnis fu:r den Bau
   der Webseiten verwenden, achten Sie daher unbedingt darauf, dass
   Sie u:ber genu:gend Plattenplatz auf dieser Partition verfu:gen.

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

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

  8.1.2. Die flexible Methode: Ein lokales doc/www-CVS-Repository
  verwenden

   Diese Methode bietet Ihnen (wie bereits erwa:hnt), mehr
   Flexibilita:t, Sie mu:ssen aber den Port oder das Paket
   net/cvsup-without-gui installieren.

     Anmerkung: Um net/cvsup-without-gui u:ber die Ports-Sammlung zu
     installieren, muss zusa:tzlich der Port lang/ezm3 (ein
     Modula 3-Compiler) installiert werden. Die Installation dieses
     Ports ist sehr zeitintensiv, daher ist es in der Regel am
     einfachsten, CVSup als Paket (Package) zu installieren.

   CVSup besitzt einen speziellen "cvs"-Modus, mit dem Sie
   ",v"-Dateien (aus denen ein CVS-Repository besteht) auschecken
   ko:nnen. Dies ist mit csup derzeit noch nicht mo:glich.
   Weiterfu:hrende Informationen zu CVSup finden Sie im Abschnitt
   Synchronisation der Quellen des FreeBSD-Handbuchs.

   Das supfile im folgenden Beispiel checkt alle cvs-Sammlungen aus,
   die Sie fu:r den Bau der Webseiten beno:tigen und speichert Sie in
   einem lokalen CVS-Repository:

 #
 # This file will create a local CVS repository
 # with the collections required for a complete
 # FreeBSD website rebuild. It should be used with
 # cvsup *only* (csup will not work)

 *default host=cvsup10.FreeBSD.org
 *default base=/var/db
 *default prefix=/usr/dcvs
 *default release=cvs
 *default delete use-rel-suffix
 *default compress

 # The following collections are needed
 # for the website build

 ports-base
 doc-all
 www

 # These collections are needed
 # for CVS functionality

 cvsroot-common
 cvsroot-ports
 cvsroot-doc

   A:ndern Sie den Eintrag default host in einen CVSup-Spiegelserver
   in Ihrer Na:he, bevor Sie mit dem Checkout beginnen. Ausserdem
   sollten Sie den Eintrag default prefix a:ndern, wenn Sie die
   ausgecheckten Dateien an einem anderen Ort speichern wollen.
   Danach speichern Sie die Datei beispielsweise als doc-www-cvsfile
   ab und fu:hren den folgenden Befehl aus:

 # cvsup -g -L2 doc-www-cvsfile

   Zusa:tzlich sollten Sie die Umgebungsvariable CVSROOT in den
   Startdateien Ihrer Shell setzen. Dazu nehmen Sie beispielsweise
   den folgenden Eintrag in die Datei ~/.cshrc auf (wenn Sie die csh
   einsetzen):

 setenv CVSROOT /usr/dcvs

   Wenn Sie diese Variable gesetzt haben, ko:nnen Sie die Option -d
   (siehe weiter unten) weglassen, wenn Sie cvs-Operationen im
   Repository ausfu:hren:

   Derzeit beno:tigen Sie fu:r ein Repository, das nur die zum Bau
   der Webseiten no:tigen Dateien entha:lt, mehr als 400 MB freien
   Plattenplatz. Der Bau der Webseiten erfordert tempora:r weitere
   200 MB. Nachdem cvsup seine Arbeit beendet hat, ko:nnen Sie die
   Dateien in das Verzeichnis, in dem Sie die Webseiten bauen wollen,
   auschecken:

 # mkdir /usr/build
 # cd /usr/build
 # cvs -d /usr/dcvs -R co -AP doc www ports

   Der letzte Befehl entspricht dem Auschecken der Dateien von einem
   CVSup-Server mit csup. Danach haben Sie ein Bau-Verzeichis analog
   zur csup-Methode.

   cvsup erlaubt es Ihnen auch, Ihr CVS-Repository regelma:ssig zu
   aktualisieren. Im Gegensatz zum ersten Aufruf dauern diese
   Aktualisierungen in der Regel nur wenige Minuten.

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

8.2. Die Webseiten bauen

   Nachdem Sie eine der beiden Methoden erfolgreich ausgefu:hrt
   haben, ko:nnen Sie mit dem Bau der Webseiten 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 www/en wechseln und dort den Befehl make(1)
       all ausfu:hren.

 # cd www/en
 # make all

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

8.3. Installieren der Webseiten auf Ihrem Server

    1. Wechseln Sie wieder in das Verzeichnis en, falls Sie dieses
       inzwischen verlassen haben.

 # cd /usr/build/www/en

    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

   CVSROOT

           Der Ort des CVS-Baums. Sie sollten diese Variable setzen,
           wenn Sie die CVSup-Methode verwenden.

 # CVSROOT=/usr/dcvs; export CVSROOT

           CVSROOT ist eine Umgebungsvariable. Sie mu:ssen sie daher
           auf der Kommandozeile oder in Ihren .dot-Dateien
           (beispielsweise in ~/.profile) setzen. Die genaue Syntax
           ha:ngt von der von Ihnen eingesetzten Shell (das letzte
           Beispiel gilt nur fu:r die bash und bash-a:hnliche Shells)
           ab.

   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 www. Alle Dokumente des doc-Verzeichnisses
           (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 www installiert. Alle weiteren Sprachen
           (ausgenommen Englisch) werden ignoriert. Dazu ein
           Beispiel:

 # make WEB_LANG="el es hu nl" 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
   CVS-Repository (als Minimum den Dokumentationsteil) anzulegen,
   entweder mit CTM oder mit CVSup. Das Kapitel "Das Neueste und
   Beste" des Handbuchs beschreibt die Nutzung dieser Programme.

   Sie sollten ausserdem mit CVS vertraut sein. Damit ist es
   mo:glich, festzustellen, was sich zwischen einzelnen Versionen
   eines Dokuments gea:ndert hat.

   [XXX Aufgabe -- Ein Tutorial schreiben, das die Verwendung von
   CVSup beschreibt, um die Dokumentation herunterzuladen,
   auszuchecken und festzustellen, was sich zwischen zwei Versionen
   gea:ndert hat.]

   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 doc/ 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:

 doc/
     sv_SE.ISO8859-1/
                      Makefile
                      books/
                            faq/
                                Makefile
                                book.sgml

   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/sgml/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: doc/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml,v 1.5 2000/07/07 18:38:38 dannyboy Exp $
 -->

   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 CVS 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: doc/es_ES.ISO8859-1/books/fdp-primer/translations/chapter.sgml,v 1.3 1999/06/24 19:12:32 jesusr Exp $
      Original revision: 1.11
 -->

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

                      Kapitel 10. Der Schreibstil

   U:bersetzt von Johann Kois.

   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 cvsup, um Ihre Quellen zu
           aktualisieren.

           Verwenden Sie cvsup, 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:

 +--- Einr&uuml;ckung (Spalte) 0
 V
 <chapter>
   <title>...</title>

   <sect1>
     <title>...</title>

     <sect2>
       <title>Einr&uuml;ckung</title>

       <para>Die erste Zeile jeder Datei hat die Einr&uuml;ckung 0, und
         zwar <emphasis>unabh&auml;ngig</emphasis> von der Einr&uuml;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>
   <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 .sgml 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
           miteingefu: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[18] 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/sgml/catalog")))
     (add-hook 'psgml-mode-hook
       '(lambda () (local-psgml-mode-hook)))

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

                  Kapitel 12. Weiterfu:hrende Quellen

   In dieser Fibel werden absichtlich nicht alle Aspekte von SGML,
   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. SGML

     * Die SGML/XML-Webseite, eine umfangreiche Quelle zu SGML.

     * Gentle introduction to SGML

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

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

   In diesem Anhang sind SGML-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 u:ber CVSup und online unter
   http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/ verfu:gbar.

   Um Irritationen zu vermeiden, bauen die SGML-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>
   <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>
   <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/sgml/docbook/dsssl/modular/catalog \ (2)
 -c /usr/local/share/sgml/docbook/catalog \
 -c /usr/local/share/sgml/jade/catalog \
 -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \(3)
 -t sgml (4) datei.sgml > 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/sgml/docbook/dsssl/modular/catalog \ (1)
 -c /usr/local/share/sgml/docbook/catalog \
 -c /usr/local/share/sgml/jade/catalog \
 -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \(2)
 -t sgml (3) datei.sgml (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
   SGML-Quelle in eine TeX-Datei umgewandelt werden.

 % jade -V tex-backend \ (1)
     -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ (2)
     -c /usr/local/share/sgml/docbook/catalog \
     -c /usr/local/share/sgml/jade/catalog \
     -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl \(3)
     -t tex (4) datei.sgml

   (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).

   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.

  Fussnoten

   [1]  Im angelsa:chischschen 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:chsichen 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             
   [11] Die englische Bezeichnung inline element wurde in Anlehnung   
        an das Wort "Fliesstext" mit "Flusselement" u:bersetzt.       
   [12] Der Standardwert fu:r size ist 3.                             
   [13] Einen kurzen historischen Abriss finden Sie unter             
        http://www.oasis-open.org/docbook/intro.shtml#d0e41.          
   [14] DocBook kennt noch andere Elemente fu:r die Auszeichnung von  
        Listen, die an dieser Stelle jedoch nicht behandelt werden.   
   [15] auf Englisch: callout                                         
   [16] 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.                                                         
   [17] Der Befehl mozilla startet das Programm mozilla.              
   [18] 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.                    

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

     Wenn Sie Fragen zu FreeBSD haben, schicken Sie eine E-Mail an
                   <de-bsd-questions@de.FreeBSD.org>.
Wenn Sie Fragen zu dieser Dokumentation haben, schicken Sie eine E-Mail
                an <de-bsd-translators@de.FreeBSD.org>.
