       Die Fibel fu:r neue Mitarbeiter des FreeBSD-Dokumentationsprojekts

  The FreeBSD Documentation Project

   Version: 49985

   Copyright (c) 1998-2014 The FreeBSD Documentation Project

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

   Redistribution and use in source (SGML DocBook) and 'compiled' forms
   (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
   modification, are permitted provided that the following conditions are
   met:

    1. Redistributions of source code (SGML DocBook) must retain the above
       copyright notice, this list of conditions and the following disclaimer
       as the first lines of this file unmodified.

    2. Redistributions in compiled form (transformed to other DTDs, converted
       to PDF, PostScript, RTF and other formats) must reproduce the above
       copyright notice, this list of conditions and the following disclaimer
       in the documentation and/or other materials provided with the
       distribution.

  Wichtig:

   THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "AS
   IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION
   PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   Zuletzt bearbeitet am 2017-02-13 21:03:05 von jkois.
   Zusammenfassung

   Vielen Dank fu:r Ihr Interesse und Ihre Mitarbeit an der
   FreeBSD-Dokumentation. Wir freuen uns u:ber jeden Beitrag.

   Diese Fibel entha:lt die Informationen, die Sie fu:r die Mitarbeit am
   FreeBSD-Dokumentationsprojekt (auch als FDP bekannt) beno:tigen. Diese
   reichen von verpflichtender und optionaler Software bis hin zur
   Philosophie des FreeBSD-Dokumentationsprojekts.

   Bitte beachten Sie, dass diese Fibel jederzeit unter Bearbeitung und noch
   nicht vollsta:ndig ist. Falls Sie einen Fehler finden, wu:rden wir uns
   freuen, wenn Sie uns daru:ber informieren.

   [ einzelne Abschnitte / komplettes Dokument ]

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

   Inhaltsverzeichnis

   Benutzungshinweise

                1. Die Eingabeaufforderungen

                2. Typographische Festlegungen

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

                4. Danksagungen

   1. U:berblick

                1.1. Die FreeBSD-Dokumentationsreihe

                1.2. Schnellstart

   2. Die Werkzeuge

                2.1. Verpflichtende Werkzeuge

                2.2. Optionale Werkzeuge

   3. Die Arbeitskopie

                3.1. Die Dokumentation und Manualpages

                3.2. Einen Spiegelserver wa:hlen

                3.3. Ein Verzeichnis fu:r die Arbeitskopie wa:hlen

                3.4. Die Arbeitskopie auschecken

                3.5. Die Arbeitskopie aktualisieren

                3.6. A:nderungen an der Arbeitskopie zuru:cknehmen

                3.7. Eine Differenzdatei erstellen

                3.8. Referenzen zu Subversion

   4. Dokumentation-Verzeichnisstruktur

                4.1. doc/ als ho:chste Ebene

                4.2. Die Verzeichnisse Sprache.Kodierung/

                4.3. Dokumentenspezifische Informationen

   5. Die Erzeugung der Zieldokumente

                5.1. DocBook in verschiedene Ausgabeformate konvertieren

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

                5.3. Die Makefiles des Dokumentationsbaums verstehen

                5.4. make(1)-Includes des FreeBSD Documentation Projects

   6. Die Webseite

                6.1. Umgebungsvariablen

                6.2. Die Webseiten bauen

   7. Die XML-Fibel

                7.1. U:berblick

                7.2. Von Elementen, Tags und Attributen

                7.3. Die DOCTYPE-Deklaration

                7.4. Die Ru:ckkehr zu SGML

                7.5. Kommentare

                7.6. Entita:ten

                7.7. Dateien mit Entita:ten einbinden

                7.8. Markierte Bereiche

                7.9. Schlussbemerkung

   8. XHMTL Markup (noch nicht u:bersetzt)

   9. DocBook Markup (noch nicht u:bersetzt)

   10. Stylesheets

                10.1. DSSSL

                10.2. CSS

   11. U:bersetzungen

   12. PO-U:bersetzungen

                12.1. Einfu:hrung

                12.2. Schnellstart

                12.3. Bisher nicht exisitierende Dokumente u:bersetzen

                12.4. U:bersetzen

                12.5. Tips fu:r U:bersetzer

                12.6. Ein u:bersetztes Dokument bauen

                12.7. Neue U:bersetzungen einreichen

   13. Der Schreibstil

                13.1. Anleitungen fu:r einen korrekten Schreibstil

                13.2. Ha:ufig verwendete Wo:rter

   14. Editor-Konfiguration

                14.1. Vim

                14.2. Emacs

                14.3. nano

   15. Weiterfu:hrende Quellen

                15.1. Das FreeBSD-Dokumentationsprojekt

                15.2. XML

                15.3. HTML

                15.4. DocBook

                15.5. Das Linux-Dokumentationsprojekt

   A. Beispiele

                A.1. DocBook-Buch (book)

                A.2. DocBook-Artikel (article)

                A.3. Ausgabeformate erzeugen

   Stichwortverzeichnis

   Tabellenverzeichnis

   5.1. Ha:ufige Ausgabeformate

   12.1. Existierende Sprachen

   Liste der Beispiele

   1. Ein Beispiel

   5.1. Das Dokument als eine einzelne HTML-Seite bauen

   5.2. Das Dokument in den Formaten HTML-Split sowie PDF bauen

   6.1. Die komplette Webseite und alle Dokumente bauen

   6.2. Nur die englische Webseite bauen

   6.3. Die Webseite bauen und installieren

   7.1. Verwendung eines Elements (Start- und Endtag)

   7.2. Verwendung eines Elements (nur Starttag)

   7.3. Verschachtelte Elemente: em

   7.4. Elemente mit Attributen nutzen

   7.5. Attribute mit einfachen Anfu:hrungszeichen

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

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

   7.8. Beispiele fu:r Kommentare in SGML

   7.9. Fehlerhafte SGML-Kommentare

   7.10. Allgemeine Entita:ten festlegen

   7.11. Parameterentita:ten festlegen

   7.12. Dateien mit Allgemeinen Entita:ten einbinden

   7.13. Dateien mit Parameterentita:ten einbinden

   7.14. Aufbau eines markierten Bereiches

   7.15. CDATA als Inhaltsmodell fu:r markierte Bereiche

   7.16. Anwendung von INCLUDE und IGNORE in markierten Abschnitten

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

   12.1. Die spanische U:bersetzung des Porter's Handbook erstellen

   12.2. Die franzo:sische U:bersetzung des PGP Keys-Artikels erstellen

   12.3. Die spanische Version des Porter's Handbook u:bersetzen

   12.4. XML-Tags beibehalten

   12.5. Die spanische Version des Porter's Handbook bauen

   12.6. Die Spanische U:bersetzung des NanoBSD-Artikel

   12.7. Koreanische UTF-8-U:bersetzung des Explaining-BSD-Artikels

   A.1. Ein DocBook-Buch (book)

   A.2. Ein DocBook-Artikel (article)

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

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

   A.5. Ein DocBook-Dokument nach Postscript umwandeln

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

                               Benutzungshinweise

   Inhaltsverzeichnis

   1. Die Eingabeaufforderungen

   2. Typographische Festlegungen

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

   4. Danksagungen

1. Die Eingabeaufforderungen

   Die folgende Tabelle entha:lt die Eingabeaufforderung eines normalen
   Benutzers sowie die des Superusers. Die in diesem Buch verwendeten
   Beispiele benutzen die jeweilige Eingabeaufforderung, um zu zeigen, als
   welcher Benutzer die Beispiele ausgefu:hrt werden.

                 Benutzer                        Eingabeaufforderung          
   Normaler Benutzer                    %                                     
   Superuser                            #                                     

2. Typographische Festlegungen

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

             Bedeutung                             Beispiel                   
   Kommandonamen                 Geben Sie ls -a ein, um alle Dateien         
                                 anzuzeigen.                                  
   Datei- und Verzeichnisnamen   Bearbeiten Sie .login.                       
   Bildschirmausgaben            You have mail.                               
   Bildschirmein- und ausgaben   % date +"The time is %H:%M"                  
                                 The time is 09:18                            
   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.            
   Text, der vom Benutzer durch  Um die Hilfeseiten nach einem bestimmten     
   seine Eingaben ersetzt werden Begriff zu durchsuchen, geben Sie man -k     
   muss                          Suchbegriff ein.                             
   Umgebungsvariablen            $HOME ist Ihr Benutzerverzeichnis.           

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

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

  Anmerkung:

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

  Tipp:

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

  Wichtig:

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

  Warnung:

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

   Beispiel 1. Ein Beispiel

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

4. Danksagungen

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

                             Kapitel 1. U:berblick

   Inhaltsverzeichnis

   1.1. Die FreeBSD-Dokumentationsreihe

   1.2. Schnellstart

   Herzlich Willkommen beim FreeBSD-Dokumentationsprojekt (auch nur FDP
   genannt). Qualitativ hochwertige Dokumentation ist sehr wichtig fu:r den
   Erfolg von FreeBSD. Jeder Beitrag, der zu diesem Projekt geleistet wird,
   ist ungemein wertvoll.

   Dieses Dokument macht den Leser mit dem FDP vertraut und erkla:rt, wie man
   selbst Dokumente erstellt und einreicht und wie die verfu:gbaren Werkzeuge
   effektiv beim Schreiben eingesetzt werden ko:nnen.

   Jeder kann zum FDP beitragen. Die einzige Voraussetzung ist die
   Bereitschaft, helfen zu wollen.

   Nach dem Lesen dieses Dokuments werden Sie in der Lage sein,

     * die vom FDP betreuten Dokumente zu erkennen,

     * die beno:tigten Dokumentations-Werkzeuge und Dateien zu installieren,

     * A:nderungen an der Dokumentation vorzunehmen,

     * A:nderungen zur Begutachtung durch das FDP einreichen ko:nnen.

1.1. Die FreeBSD-Dokumentationsreihe

   Das FDP umfasst vier verschiedene Kategorien:

     * Handbook: Das Handbuch ist die umfassende Quelle und Referenz fu:r
       FreeBSD-Benutzer.

     * FAQ: Eine Sammlung von kurzen Fragen und Antworten zu Themen, die auf
       den verschiedenen Mailinglisten und in auf FreeBSD spezialisierten
       Foren regelma:ssig diskutiert werden. Lange und komplizierte Antworten
       werden Sie hier nicht finden.

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

     * Die Webseite: Die Hauptpra:senz von FreeBSD im Internet, zu erreichen
       unter http://www.FreeBSD.org oder einem der zahlreichen Spiegelserver.
       Fu:r viele Menschen ist sie der erste Kontakt mit FreeBSD.

   U:bersetzer-Teams sind fu:r die U:bersetzung des Handbuchs und der
   Webseite in verschiedene Sprachen verantwortlich. Manualpages werden
   derzeit nicht u:bersetzt.

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

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

   Committ-Nachrichten des FDP sind u:ber svn abrufbar und werden zusa:tzlich
   unter http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all archiviert.

   Beide Repositories sind auch u:ber ein Web-Interface erreichbar:
   https://svnweb.FreeBSD.org/doc/ sowie https://svnweb.FreeBSD.org/base/.

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

1.2. Schnellstart

   Dieser Abschnitt beschreibt, was Sie tun mu:ssen, bevor Sie A:nderungen an
   der FreeBSD-Dokumentation vornehmen ko:nnen. Abonnieren Sie zuerst die
   Mailingliste FreeBSD documentation project. Einige Mitglieder dieser
   Mailingliste sind auch auf dem IRC-Kanal #bsddocs auf EFnet erreichbar.
   Nehmen Sie mit Ihnen Kontakt auf, wenn Sie Fragen oder Probleme bei der
   Arbeit an der FreeBSD-Dokumentation haben.

    1. Installieren Sie den Metaport textproc/docproj als Port oder Paket, um
       automatisch alle fu:r die Arbeit an der Dokumentation beno:tigten
       Werkzeuge zu installieren.

    2. Installieren Sie eine lokale Arbeitskopie der Dokumentation von einem
       Spiegelserver des FreeBSD-Repository nach ~/doc (lesen Sie dazu auch
       Kapitel 3, Die Arbeitskopie).

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

    3. Ihr Texteditor sollte fu:r die Arbeit an der FreeBSD-Dokumentation wie
       folgt konfiguriert sein:

          * Zeilenumbruch nach 70 Zeichen.

          * Tabstop auf 2 Zeichen.

          * 8 Leerzeichen sollen durch einen Tabstop ersetzt werden.

       Konfigurationen fu:r einige ha:ufig verwendete Editoren finden Sie im
       Kapitel 13, Der Schreibstil.

    4. Aktualisieren Sie Ihre lokale Arbeitskopie:

 % svn up ~/doc

    5. Bearbeiten Sie die Datei. Bevor Sie umfangreiche A:nderungen an einer
       Datei vornehmen, ku:ndigen Sie die geplanten A:nderungen bitte auf der
       Mailingliste an.

       Eine Auflistung ha:ufig verwendeter Tags und Entities finden Sie in
       Kapitel 8, XHMTL Markup (noch nicht u:bersetzt) und in Kapitel 9,
       DocBook Markup (noch nicht u:bersetzt).

    6. Nachdem Sie Ihre A:nderungen vorgenommen haben, pru:fen Sie diese auf
       potentielle Probleme:

 % igor -R filename.xml | less -RS

       Werden Fehler gemeldet, editieren Sie die Datei erneut. Speichern Sie
       das Ergebnis und fu:hen Sie den Test erneut aus. Wiederholen Sie dies
       solange, bis keine Fehler mehr gemeldet werden.

    7. Bauen Sie die Dokumentation immer, bevor Sie A:nderungen einreichen.
       Dazu fu:hren Sie make im Hauptverzeichnis des Dokuments aus, dass Sie
       gerade bearbeiten. Um beispielsweise die deutsche Version des
       FreeBSD-Handbuchs als einzelne HTML-Dateien zu bauen, fu:hren Sie make
       im Verzeichnis de_DE.ISO8859-1/books/handbook/ aus. Durch diesen
       Schritt wird sichergestellt, dass Ihre A:nderungen den Bau der
       Dokumentation nicht wegen eines Fehlers abbrechen.

    8. Wenn Ihre A:nderungen abgeschlossen und erfolgreich getestet wurden,
       erzeugen Sie eine "Differenzdatei" mit Ihren A:nderungen:

 % cd ~/doc
 % svn diff > bsdinstall.diff.txt

       Geben Sie der Differenzdatei einen aussagekra:ftigen Namen. Im
       angegebenen Bespiel wurden A:nderungen im Abschnitt bsdinstall des
       Handbuchs vorgenommen.

    9. Reichen Sie Ihre A:nderungen u:ber das webbasierte
       Problembericht-Formular ein. Geben Sie eine kurze Beschreibung in der
       Form [patch] kurze Beschreibung des Problems ein. Als Kategorie
       wa:hlen Sie docs und als Klasse doc-bug. Danach geben Sie eine
       Beschreibung Ihrer A:nderungen ein sowie eventuelle weitere wichtige
       Punkte. Verwenden Sie danach den Button [ Browse... ], um Ihre
       Differenzdatei hochzuladen.

                            Kapitel 2. Die Werkzeuge

   Inhaltsverzeichnis

   2.1. Verpflichtende Werkzeuge

   2.2. Optionale Werkzeuge

   Um die FreeBSD-Dokumentation zu verwalten und in verschiedene Formate zu
   konvertieren, werden diverse Werkzeuge verwendet. Einige dieser Werkzeuge
   sind verpflichtend und mu:ssen auf Ihrem System installiert sein, bevor
   Sie den Beispielen in den folgenden Kapiteln folgen ko:nnen. Andere sind
   hingegen optional und dienen dazu, zusa:tzliche Funktionalita:t
   bereitzustellen oder das Erzeugen der Dokumentation zu vereinfachen.

2.1. Verpflichtende Werkzeuge

   Installieren Sie zuerst den Port textproc/docproj u:ber die
   Ports-Sammlung. Dieser Metaport installiert alle verpflichtenden Werkzeuge
   fu:r die Arbeit an der FreeBSD-Dokumentation. Einige dieser Komponenten
   werden in den folgenden Abschnitten na:her beschrieben.

  2.1.1. Die DTDs und die Entita:ten

   Das FDP benutzt verschiedene Document Type Definitions (DTDs) und diverse
   XML-Entita:tensa:tze. Diese werden durch den Port textproc/docproj
   automatisch installiert.

   XHTML DTD (textproc/xhtml)

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

   DocBook DTD (textproc/docbook-xml-450)

           DocBook ist als Auszeichnungssprache fu:r technische
           Dokumentationen entwickelt worden. Ein Grossteil der
           FreeBSD-Dokumentation wird mittels DocBook erstellt.

   ISO 8879 entities (textproc/iso8879)

           Enties des ISO 8879:1986-Standards, 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.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, teTeX und Modular DocBook Stylesheets (print/jadetex, print/teTeX
   und textproc/dsssl-docbook-modular)

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

           Ist nicht geplant, die Dokumente in einem dieser Formate zu
           erzeugen (wenn also XHTML und Text ausreichend sind), brauchen Sie
           diese nicht zu installieren. Dazu deaktivieren Sie diese Option im
           Konfigurationsbildschirm des Ports textproc/docproj.

   Vim (editors/vim)

           Ein beliebter Texteditor zur Bearbeitung von XML und davon
           abgeleiteten Dokumenten wie DocBook XML.

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

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

                          Kapitel 3. Die Arbeitskopie

   Inhaltsverzeichnis

   3.1. Die Dokumentation und Manualpages

   3.2. Einen Spiegelserver wa:hlen

   3.3. Ein Verzeichnis fu:r die Arbeitskopie wa:hlen

   3.4. Die Arbeitskopie auschecken

   3.5. Die Arbeitskopie aktualisieren

   3.6. A:nderungen an der Arbeitskopie zuru:cknehmen

   3.7. Eine Differenzdatei erstellen

   3.8. Referenzen zu Subversion

   Die Arbeitskopie ist eine Kopie des FreeBSD Dokumentationsrepositories,
   die Sie auf Ihren lokalen Computer heruntergeladen haben. A:nderungen an
   der Dokumentation werden in der Arbeitskopie durchgefu:hrt und getestet.
   Patches fu:r A:nderungen im Hauptrepository werden aus der Arbeitskopie
   erzeugt, nachdem Sie Ihre A:nderungen durchgefu:hrt haben.

   Eine komplette Kopie des Dokumentationsbaums ist etwa 700 Megabyte gross.
   Damit Sie die Dokumentation auch in verschiedenen Formaten testen und
   bauen ko:nnen, sollten Sie fu:r das Repository mindestens 1 Gigabyte an
   freiem Speicherplatz bereitstellen.

   Die Dateien der FreeBSD-Dokumentation werden mit Subversion verwaltet.
   Falls es auf Ihrem System noch nicht vorhanden ist, wird dieses Werkzeug
   vom Port textproc/docproj automatisch installiert.

3.1. Die Dokumentation und Manualpages

   Die FreeBSD-Dokumentation besteht nicht nur aus Bu:chern und Artikeln.
   Auch die Manualpages fu:r alle Befehle und Konfigurationsdateien sind Teil
   des FDP. Die Dokumentation ist dabei auf zwei Repositories verteilt: doc
   fu:r Bu:cher und Artikel sowie base fu:r das Betriebssystem und
   Manualpages. Um Manualpages zu bearbeiten, muss zusa:tzlich das Repository
   base ausgecheckt werden.

   Ein Repository kann multiple Versionen der Dokumentatation enthalten.
   A:nderungen werden in der Regel aber immer nur an der aktuellen Version
   durchgefu:hrt, die als head bezeichnet wird.

3.2. Einen Spiegelserver wa:hlen

   Um die Geschwindigkeit zu erho:hen (und die Downloadzeit zu reduzieren),
   wa:hlen Sie bitte aus der Liste der Subversion Spiegelserver einen Server
   in Ihrer Na:he. Ersetzen Sie dazu in den folgenden Beispielen die URL
   https://svn0.us-west.FreeBSD.org/ durch die des von Ihnen gewa:hlten
   Spiegelservers.

3.3. Ein Verzeichnis fu:r die Arbeitskopie wa:hlen

   Die FreeBSD-Dokumentation wird u:blicherweise unter /usr/doc/, Quellcode
   (inklusive Manualpages) unter /usr/src/ installiert. Es ist sinnvoll,
   Arbeitskopien in einen anderen Ordner auszuchecken, um potentielle
   Konflikte mit bereits in diesen Ordnern vorhandenen Dokumenten zu
   vermeiden. Die folgenden Beispiele verwenden daher die Verzeichnisse ~/doc
   sowie ~/src. Bei beiden Verzeichnissen handelt es sich um
   Unterverzeichnisse des home-Verzeichnisses des jeweiligen Benutzers.

3.4. Die Arbeitskopie auschecken

   Der Download einer Arbeitskopie wird als checkout bezeichnet und erfolgt
   u:ber den Befehl svn checkout. Das folgende Beispiel checkt die aktuelle
   Version der Dokumentatation (head) aus dem Hauptdokumentationsbaum aus:

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

   Das Auschecken des Quellcodes fu:r die Arbeit an den Manualpages erfolgt
   analog:

 % svn checkout https://svn0.us-west.FreeBSD.org/base/head ~/src

3.5. Die Arbeitskopie aktualisieren

   Die Dokumente und Dateien im FreeBSD-Repository a:ndern sich beinahe
   ta:glich. A:nderungen werden durchgefu:hrt und committed. Bereits kurz
   nach einem Checkout kann es daher Unterschiede zwischen Ihrer Arbeitskopie
   und dem FreeBSD-Hauptrepository geben. Um eine lokale Arbeitskopie auf den
   Stand des Hauptrepository zu aktualisieren, wenden Sie den Befehl svn
   update auf das Verzeichnis an, in dem sich Ihre lokale Arbeitskopie
   befindet:

 % svn update ~/doc

   Gewo:hnen Sie sich an, svn update auszufu:hren, bevor Sie Dokumente
   bearbeiten. Sonst kann es passieren, dass das Dokument in der Zwischenzeit
   bearbeitet wurde, Ihre lokale Kopie diese A:nderungen aber noch nicht
   entha:lt. Es ist deutlich einfacher, die aktuelle Version zu bearbeiten,
   als Ihre a:lteren lokalen A:nderungen mit den aktuellen A:nderungen des
   Repositories zu kombininieren.

3.6. A:nderungen an der Arbeitskopie zuru:cknehmen

   Manchmal ist es notwendig, durchgefu:hrte A:nderungen zuru:ck zu nehmen
   oder u:berhaupt von vorne zu beginnen. A:nderungen an einer Datei ko:nnen
   u:ber den Befehl svn revert "zuru:ckgesetzt" werden (die Datei ist danach
   wieder in ihrer urspru:nglichen Version vorhanden). Wollen Sie
   beispielsweise Ihre A:nderungen an der Datei chapter.xml zuru:cksetzen, um
   die unbearbeitete Originalversion zu erhalten, geben Sie den folgenden
   Befehl ein:

 % svn revert chapter.xml

3.7. Eine Differenzdatei erstellen

   Nachdem Sie eine oder mehrere Dateien bearbeitet haben, mu:ssen Sie die
   Unterschiede zwischen Ihrer lokalen Arbeitskopie und dem
   FreeBSD-Repository in einer Datei sammeln, bevor Sie Ihre A:nderungen
   einreichen ko:nnen. Diese Dateien werden als diff-Dateien bezeichnet und
   ko:nnen durch den Befehl svn diff erzeugt werden:

 % cd ~/doc
 % svn diff > doc-fix-spelling.diff

   Geben Sie der Datei einen Namen, die den Inhalt beschreibt. Die
   Differenzdatei im Beispiel entha:lt Rechtschreibkorrekturen fu:r den
   gesamten Dokumentationsbaum.

   Wenn Sie Ihre A:nderungen u:ber das Webformular "Submit a FreeBSD problem
   report" einreichen wollen, fu:gen Sie bitte die Erweiterung .txt an den
   Dateinamen an, damit das Formular sicher erkennt, dass Sie gewo:hnlichen
   Text hochladen wollen.

   Vorsicht: svn diff protokolliert ALLE A:nderungen im aktuellen Verzeichnis
   (und dessen Unterverzeichnissen). Wollen Sie einige dieser A:nderungen
   noch nicht einreichen, mu:ssen Sie angeben, fu:r welche Dateien Sie eine
   Differenzdatei erstellen wollen.

 % cd ~/doc
 % svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diff

3.8. Referenzen zu Subversion

   Diese Beispiele haben Ihnen den prinzipiellen Umgang mit Subversion
   gezeigt. Weitere detaillierte Informationen finden Sie im Subversion Book
   sowie in der Subversion documentation.

                  Kapitel 4. Dokumentation-Verzeichnisstruktur

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   4.1. doc/ als ho:chste Ebene

   4.2. Die Verzeichnisse Sprache.Kodierung/

   4.3. Dokumentenspezifische Informationen

   Die Struktur der Dateien und Ordner unterhalb von doc/ hilft dabei,

    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, leichter zu machen.

   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.

4.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                           Bedeutung                           
   share         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 XML-Unterstu:tzung no:tigen Dateien (darunter   
                 die FreeBSD DocBook DTD) unter share/xml befinden.           
   lang.encoding Fu:r jede verfu:gbare Sprache und Kodierung existiert ein    
                 eigenes Unterverzeichnis. Beispiele dafu:r sind              
                 en_US.ISO8859-1/ oder zh_TW.UTF-8/. 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.  

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

   Verzeichis                            Bedeutung                            
   articles   DocBook-formatierte Artikel (article) oder a:hnliche Dokumente. 
              Meist relativ kurz und in Abschnitte aufgeteilt. Artikel sind   
              in der Regel als ein einziges, grosses XHTML-Dokument           
              verfu:gbar.                                                     
   books      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 XHTML-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.      
   man        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.

4.3. Dokumentenspezifische Informationen

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

  4.3.1. Das Handbuch

    books/handbook/

   Das Handbuch wurde unter Verwendung von DocBook XML (und der vom FreeBSD
   Project erweiterten XML DocBook-DTD) geschrieben.

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

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

      4.3.1.1.1. Makefile

   Das Makefile definiert verschiedene Variablen zur Konvertierung
   derXML-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.

      4.3.1.1.2. book.xml

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

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

      4.3.1.1.3. Verzeichnis/chapter.xml

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

   Entha:lt eine Kapiteldatei beispielsweise die Eintra:ge

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

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

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

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

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

  Wichtig:

   Benennen Sie Kapitel und Verzeichnisse nicht nach Ihrer Reihenfolge
   innerhalb des Handbuchs. Dann fu:hrt eine Umstrukturierung des Handbuchs
   im Normalfall nicht dazu, dass dafu:r Dateien umbenannt werden mu:ssen (es
   sei denn, einzelne Kapitel werden neu aufgenommen oder entfernt).

   Die Datei chapter.xml ist keine komplette XML-Datei. Dies bedeutet, dass
   sie nicht alleine gebaut werden kann, sondern nur als Teil des Handbuchs.

                   Kapitel 5. Die Erzeugung der Zieldokumente

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   5.1. DocBook in verschiedene Ausgabeformate konvertieren

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

   5.3. Die Makefiles des Dokumentationsbaums verstehen

   5.4. make(1)-Includes des FreeBSD Documentation Projects

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

5.1. DocBook in verschiedene Ausgabeformate konvertieren

   Aus einer einzigen DocBook-Quellcodedatei ko:nnen verschiedene
   Ausgabeformate erstellt werden. Welches Dateiformat erstellt wird, wird
   u:ber die Variable FORMATS festgelegt. Eine Liste aller verfu:gbaren
   Formate ist in KNOWN_FORMATS gespeichert:

 % cd ~/doc/en_US.ISO8859-1/books/handbook
 % make -V KNOWN_FORMATS

   Tabelle 5.1. Ha:ufige Ausgabeformate

    FORMATS          Dateityp                      Beschreibung               
   html       HTML, Einzeldatei      Eine einzelne book.html oder             
                                     article.html.                            
                                     Multiple HTML-Dateien, eine fu:r jedes   
                                     Kapitel oder fu:r jeden Abschnitt.       
   html-split HTML, multiple Dateien Dieser Typ wird in der Regel fu:r die    
                                     Nutzung des Dokuments auf einer          
                                     Internetseite verwendet.                 
   pdf        PDF                    Portable Document Format                 

   Welches Format verwendet wird, ha:ngt vom jeweiligen Dokument ab, in der
   Regel handelt es sich aber um html-split. Weitere Formate werden u:ber die
   Variable FORMATS angegeben. Dabei ko:nnen Sie ein einzelnes Format, aber
   auch mehrere Formate gleichzeitig definieren.

   Beispiel 5.1. Das Dokument als eine einzelne HTML-Seite bauen

 % cd ~/doc/en_US.ISO8859-1/books/handbook
 % make FORMATS=html

   Beispiel 5.2. Das Dokument in den Formaten HTML-Split sowie PDF bauen

 % cd ~/doc/en_US.ISO8859-1/books/handbook
 % make FORMATS="html-split pdf"

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

   Die folgende Werkzeuge werden beno:tigt, um die FDP-Dokumente zu bauen und
   zu installieren.

     * Das wichtigste Werkzeug ist make(1), genauer Berkeley Make.

     * Der Bau von Paketen erfolgt unter FreeBSD mit pkg_create(1).

     * gzip(1) dient zur Erstellung komprimierter Versionen der
       Dokumentation. bzip2(1) wird ebenfalls unterstu:tzt. Wollen Sie Pakete
       der Dokumentation erstellen, beno:tigen Sie auch tar(1).

     * Mit install(1) installieren Sie die Dokumentation auf Ihrem System.

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

  5.3.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(1)-Variablen
   SUBDIR, COMPAT_SYMLINK, und DOC_PREFIX.

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

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

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

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

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

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

   Die letzte Zeile bindet doc.project.mk, die zentrale, projektweite
   make(1)-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.

  5.3.2. Dokument-Makefiles

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

   Dazu ein Beispiel:

 MAINTAINER=nik@FreeBSD.org

 DOC?= book

 FORMATS?= html-split html

 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=

 # SGML content
 SRCS=  book.xml

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

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

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

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

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

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

5.4. make(1)-Includes des FreeBSD Documentation Projects

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

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

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

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

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

  5.4.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"

    5.4.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 nicht, 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.

    5.4.1.2. Bedingungen

   Die Zeile .if defined(DOC) ist ein Beispiel fu:r eine make(1)-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.

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

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

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

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

    5.4.2.3. Weitere Bedingungen

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

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

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

    5.4.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 6. Die Webseite

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   6.1. Umgebungsvariablen

   6.2. Die Webseiten bauen

   Die FreeBSD Webseite ist Teil der FreeBSD-Dokumentation. Die Dateien der
   englischen Webseite befinden sich im Unterverzeichnis
   en_US.ISO8859-1/htdocs des Dokumentationsbaum (in diesem Beispiel unter
   ~/doc).

6.1. Umgebungsvariablen

   Sie haben die Mo:glichkeit, u:ber Umgebungsvariablen festzulegen, welchen
   Teil der Webseite Sie bauen wollen und in welches Verzeichnis Sie die
   fertige Webseite installieren wollen.

  Tipp:

   Beim Bau der Webseiten (durch make(1)) wird angenommen, dass definierte
   Variablen gesetzt sind (dies gilt auch dann, wenn die Variable leer ist!).
   Die folgenden Beispiele zeigen die empfohlene Definition und Nutzung der
   mo:glichen Variablen. Wenn Sie diese Variablen auf andere Werte oder
   Methoden setzen, kann es zu u:berraschenden Ergebnissen kommen.

   DESTDIR

           DESTDIR legt fest, in welches Verzeichnis die fertig gebaute
           Webseite installiert werden soll.

           Diese Variable wird am besten durch env(1) oder durch die
           Shell-eigene Methode zum setzen von Variablen, also setenv fu:r
           csh(1) oder export fu:r sh(1).

   ENGLISH_ONLY

           Default: Nicht definiert. Baue die Webseite inklusive aller
           U:bersetzungen.

           ENGLISH_ONLY=yes: Baue nur die englischen Dokumente und ignoriere
           alle U:bersetzungen.

   WEB_ONLY

           Default: Nicht definiert. Baue sowohl die Webseite als auch alle
           Bu:cher und Artikel.

           WEB_ONLY=yes: Baue oder installiere nur die HTML-Seiten im
           Verzeichis en_US.ISO8859-1/htdocs. Ignoriere alle anderen
           Verzeichnisse und Dokumente, Bu:cher und Artikel.

   WEB_LANG

           Default: Nicht definiert. Baue die Webseite in allen verfu:gbaren
           Sprachen.

           Geben Sie die Sprachen (durch Leerzeichen getrennt) an, in denen
           Sie die Webseite bauen und/oder installieren wollen. Die Namen der
           zu bauenden Sprachen entsprechen dabei den Namen der
           Dokumentwurzelverzeichnisse. Wollen Sie beispielsweise die
           deutschen und franzo:sischen Dokumente einschliessen:

 WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"

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

6.2. Die Webseiten bauen

   Nachdem Sie die Quellen der Webseite erfolgreich heruntergeladen haben,
   ko:nnen Sie mit dem Bau der Webseite beginnen.

   Die Installation der Webseiten wird als root ausgefu:hrt, weil die
   Berechtigungen des Webserver-Verzeichnisses den Schreibzugriff fu:r
   normale Benutzer verhindern. Zu Testzwecken ko:nnen die Dateien auch als
   normaler Benutzer in ein tempora:res Verzeichnis installiert werden.

   In den folgenden Beispielen werden die Webseiten durch den Benutzer jru in
   dessen Heimatverzeichnis, also unter /usr/home/jru/doc, gebaut.

  Tipp:

   Der Bau der Webseiten erfordert die Datei INDEX der Ports-Sammlung und
   schla:gt fehl, wenn /usr/ports nicht existiert. Der einfachste Weg, dies
   zu vermeiden, ist die Installation der Ports-Sammlung.

   Beispiel 6.1. Die komplette Webseite und alle Dokumente bauen

   Bauen Sie die Webseite und alle Dokumente. Die erzeugten Dateien
   verbleiben dabei im Dokumentationsbaum:

 % cd ~/doc/en_US.ISO8859-1/htdocs/
 % make all

   Beispiel 6.2. Nur die englische Webseite bauen

   Bauen Sie nur die englische Webseite als Benutzer jru und installieren Sie
   die erzeugten Dateien nach /tmp/www, um die Webseite testen zu ko:nnen:

 % cd ~/doc/en_US.ISO8859-1/htdocs/
 % env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install

   A:nderungen an statischen Dateien ko:nnen Sie einfach testen, indem Sie
   die gea:nderten Dateien in Ihrem Webbrowser aufrufen. Haben Sie Seite wie
   eben gezeigt gebaut, ko:nnen Sie sich die gea:nderte Startseite ganz
   einfach anzeigen lassen:

 % firefox /tmp/www/data/index.html

   A:nderungen an dynamischen Dateien ko:nnen allerdings nur auf einem
   Webserver (der auf dem lokalen System la:uft) getestet werden. Nachdem Sie
   die Website wie weiter oben gezeigt gebaut haben, ko:nnen Sie www/apache24
   mit folgender Konfigurationsdatei /usr/local/etc/apache24/httpd.conf
   starten und Ihre A:nderungen testen:

 # httpd.conf for testing the FreeBSD website
 Define TestRoot "/tmp/www/data"

 # directory for configuration files
 ServerRoot "/usr/local"

 Listen 80

 # minimum required modules
 LoadModule authz_core_module libexec/apache24/mod_authz_core.so
 LoadModule mime_module libexec/apache24/mod_mime.so
 LoadModule unixd_module libexec/apache24/mod_unixd.so
 LoadModule cgi_module libexec/apache24/mod_cgi.so
 LoadModule dir_module libexec/apache24/mod_dir.so

 # run the webserver as user and group
 User www
 Group www

 ServerAdmin you@example.com
 ServerName fbsdtest

 # deny access to all files
 <Directory />
     AllowOverride none
     Require all denied
 </Directory>

 # allow access to the website directory
 DocumentRoot "${TestRoot}"
 <Directory "${TestRoot}">
     Options Indexes FollowSymLinks
     AllowOverride None
     Require all granted
 </Directory>

 # prevent access to .htaccess and .htpasswd files
 <Files ".ht*">
     Require all denied
 </Files>

 ErrorLog "/var/log/httpd-error.log"
 LogLevel warn

 # set up the CGI script directory
 <Directory "${TestRoot}/cgi">
     AllowOverride None
     Options None
     Require all granted
     Options +ExecCGI
     AddHandler cgi-script .cgi
 </Directory>

 Include etc/apache24/Includes/*.conf

   Starten Sie den Webserver wie folgt:

 # service apache24 onestart

   Die Webseite ist danach unter der Adresse http://localhost erreichbar.
   Beachten Sie aber, dass viele Links auf die echte FreeBSD-Webseite zeigen.
   Daher werden diese Links die externe Seite aufrufen und nicht Ihre lokale
   Testversion. Um dies zu verhindern und einen kompletten lokalen Test Ihrer
   lokalen Seite durchzufu:hren, mu:ssen Sie DNS tempora:r umkonfigurieren,
   damit www.FreeBSD.org als localhost oder als Ihre lokale IP-Adresse
   aufgelo:st wird.

   Beispiel 6.3. Die Webseite bauen und installieren

   Bauen Sie die Webseite und alle Dokumente als Benutzer jru. Installieren
   Sie die erzeugten Dateien als root in das Standardverzeichnis, also nach
   /root/public_html:

 % cd ~/doc/en_US.ISO8859-1/htdocs
 % make all
 % su -
 Password:
 # cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs
 # make install

   Veraltete (und nicht mehr verwendete) Dateien werden wa:hrend der
   Installation nicht automatisch entfernt. Der folgende Befehl findet (und
   lo:scht) alle Dateien im Installationsverzeichnis, die in den letzten drei
   Tagen nicht aktualisiert wurden:

 # find /usr/local/www -ctime 3 -delete

                            Kapitel 7. Die XML-Fibel

   Inhaltsverzeichnis

   7.1. U:berblick

   7.2. Von Elementen, Tags und Attributen

   7.3. Die DOCTYPE-Deklaration

   7.4. Die Ru:ckkehr zu SGML

   7.5. Kommentare

   7.6. Entita:ten

   7.7. Dateien mit Entita:ten einbinden

   7.8. Markierte Bereiche

   7.9. Schlussbemerkung

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

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

7.1. U:berblick

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

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

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

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

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

 % rm /tmp/foo

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

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

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

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

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

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

   Die Auszeichnungselemente sind deutlich vom eigentlichen Inhalt zu
   unterscheiden.

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

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

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

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

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

  Anmerkung:

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

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

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

  7.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 7.6. .profile, fu:r sh(1) und bash(1) Benutzer

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 % onsgmls -s beispiel.xml

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

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

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

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

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

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

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

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

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

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

  7.3.1. Formale O:ffentliche Bezeichner

  Anmerkung:

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

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

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

   Besitzer

           Nennt den Besitzer des o:ffentlichen Bezeichners.

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

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

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

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

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

   Schlu:sselwort

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

   Beschreibung

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

   Sprache

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

    7.3.1.1. Die catalog-Dateien

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

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

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

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

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

    7.3.1.2. Die Variable SGML_CATALOG_FILES

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

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

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

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

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

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

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

   Allerdings sollte das schon geschehen sein.

  7.3.2. Alternativen zu Formalen O:ffentlichen Bezeichnern

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

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

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

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

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

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

7.5. Kommentare

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

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

   Beispiel 7.8. Beispiele fu:r Kommentare in SGML

 <!-- Testkommentar -->

 <!-- Text innerhalb eines Kommentars -->

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

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

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

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

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

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

  7.5.1. Fingeru:bungen...

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

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

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

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

  7.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 7.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">
 ]>

  7.6.3. Fingeru:bungen...

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

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

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

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

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

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

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

    2. Validieren Sie diese Datei mit onsgmls

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

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

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

       Versuchen Sie, die Beispieldatei mittels osgmlnorm zu normalisieren:

 % osgmlnorm beispiel.xml > beispiel.html

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

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

 % osgmlnorm -d beispiel.xml > beispiel.html

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

  7.7.1. Dateien mit Allgemeinen Entita:ten einbinden

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

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

   Beispiel 7.12. Dateien mit Allgemeinen Entita:ten einbinden

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

 <html>

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

  Warnung:

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

  7.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 7.13. Dateien mit Parameterentita:ten einbinden

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

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

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

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

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

  7.7.3. Fingeru:bungen...

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

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

 <p>Erster Absatz.</p>

       an.

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

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

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

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

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

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

 % osgmlnorm -d beispiel.xml > beispiel.html

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

    7.7.3.2. Binden Sie Dateien mit Parameterentita:ten ein

  Anmerkung:

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

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

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

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

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

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

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

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

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

 % osgmlnorm -d beispiel.xml > beispiel.html

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

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

  7.8.1. Schlu:sselworte fu:r markierte Bereiche

    7.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 7.15. CDATA als Inhaltsmodell fu:r markierte Bereiche

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

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

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

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

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

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

  7.8.2. Fingeru:bung...

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

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

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

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

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

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

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

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

7.9. Schlussbemerkung

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

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

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

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

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

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

   [5] auf Englisch Formal Public Identifier (FPI)

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

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

   [8] auf Englisch marked sections

   [9] auf Englisch character data

   [10] auf Englisch Entity references and character data

                Kapitel 8. XHMTL Markup (noch nicht u:bersetzt)

   Dieses Kapitel ist noch nicht u:bersetzt. Lesen Sie daher bitte das
   Original in englischer Sprache. Wenn Sie bei der U:bersetzung mithelfen
   wollen, schicken Sie bitte eine E-Mail an 'FreeBSD German Documentation
   Project' <de-bsd-translators@de.FreeBSD.org>.

               Kapitel 9. DocBook Markup (noch nicht u:bersetzt)

   Dieses Kapitel ist noch nicht u:bersetzt. Lesen Sie daher bitte das
   Original in englischer Sprache. Wenn Sie bei der U:bersetzung mithelfen
   wollen, schicken Sie bitte eine E-Mail an 'FreeBSD German Documentation
   Project' <de-bsd-translators@de.FreeBSD.org>.

                            Kapitel 10. Stylesheets

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   10.1. DSSSL

   10.2. CSS

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

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

10.1. DSSSL

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

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

10.2. CSS

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

  10.2.1. Die DocBook-Dokumente

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

                           Kapitel 11. 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.

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

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

   11.3. Werden noch U:bersetzer beno:tigt?

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

   11.5. Welche Software wird beno:tigt?

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

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

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

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

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

   11.11. Wie lassen sich sprachspezifische Zeichen darstellen?

   11.12. Wie spricht man den Leser an?

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

11.1.  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".           
11.2.  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. Fu:r allgemeine Diskussionen zur U:bersetzung der                     
       FreeBSD-Dokumentation gibt es die Mailingliste <freebsd-translators@freebsd.org>.       
11.3.  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.                 
11.4.  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.                                          
11.5.  Welche Software wird beno:tigt?                                                         
       Es ist sehr empfehlenswert, eine lokale Kopie des FreeBSD Subversion-Repository (als    
       Minimum den Dokumentationsteil) anzulegen. Dazu geben Sie den folgenden Befehl ein:     
                                                                                               
       % svn checkout https://svn.FreeBSD.org/doc/head/ head                                   
                                                                                               
         Anmerkung:                                                                            
                                                                                               
       svn.FreeBSD.org ist ein o:ffentlicher Server. U:berpru:fen Sie das Serverzertifikat,    
       bevor Sie erstmals auf den Server zugreifen.                                            
                                                                                               
         Anmerkung:                                                                            
                                                                                               
       Damit dieser Befehl funktioniert, muss der Port devel/subversion installiert sein.      
                                                                                               
       Sie sollten ausserdem mit svn vertraut sein. Damit ist es mo:glich, festzustellen, was  
       sich zwischen einzelnen Versionen eines Dokuments gea:ndert hat.                        
                                                                                               
       Wenn Sie beispielsweise wissen wollen, was sich zwischen den Revisionen r33733 und      
       r33734 der Datei en_US.ISO8859-1/books/fdp-primer/book.xml gea:ndert hat, geben Sie den 
       folgenden Befehl ein:                                                                   
                                                                                               
       % svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml                      
11.6.  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.                                                
11.7.  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.      
11.8.  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).                 
11.9.  Ich arbeite als einziger an der U:bersetzung in diese Sprache, wie versende ich meine   
       U:bersetzungen?                                                                         
                                                                                               
       oder                                                                                    
                                                                                               
       Wir sind ein U:bersetzer-Team, und wollen Dokumente versenden, die unsere Mitglieder    
       u:bersetzt haben.                                                                       
       Stellen Sie zuerst sicher, dass Ihre U:bersetzungen korrekt organisiert sind. Sie       
       sollte sich also im existierenden Dokumentationsbaum befinden, und ohne Fehler bauen    
       lassen.                                                                                 
                                                                                               
       Zurzeit wird die FreeBSD Dokumentation unterhalb des Verzeichnisses head/ gespeichert.  
       Die direkten Unterverzeichnisse werden entsprechend der Sprachkodierung benannt, in der 
       sie geschrieben sind. Diese Kodierung nach ISO639 finden Sie auf einem FreeBSD-System   
       unter /usr/share/misc/iso639, vorausgesetzt, das System wurde nach dem 20. Januar 1999  
       gebaut.                                                                                 
                                                                                               
       Wenn in Ihrer Sprache mehrere Kodierungen (wie dies etwa fu:r Chinesisch der Fall ist)  
       vorhanden sind, existiert fu:r jede Kodierung ein eigenes Unterverzeichnis.             
                                                                                               
       Zuletzt existieren auch noch Verzeichnisse fu:r die einzelnen Dokumente.                
                                                                                               
       Die Verzeichnishierarchie fu:r eine hypothetische schwedische U:bersetzung ko:nnte etwa 
       so aussehen:                                                                            
                                                                                               
       head/                                                                                   
           sv_SE.ISO8859-1/                                                                    
                            Makefile                                                           
                            htdocs/                                                            
                                  docproj/                                                     
                            books/                                                             
                                  faq/                                                         
                                      Makefile                                                 
                                      book.xml                                                 
                                                                                               
       Bei sv_SE.ISO8859-1 handelt es sich um den Namen der U:bersetzung in der Form           
       lang.encoding. 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 Bugzilla 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.      
11.10. 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 (u:ber Bugzilla) tun, und die A:nderung anschliessend  
       in Ihre Sprache u:bersetzen.                                                            
                                                                                               
       Vielen Dank.                                                                            
11.11. Wie lassen sich sprachspezifische Zeichen darstellen?                                   
       Nicht-ASCII-Zeichen innerhalb der Dokumentation werden durch SGML-Entities dargestellt. 
                                                                                               
       Diese bestehen aus: Kaufma:nnischem Und (&), den Namen der Entity, und einem            
       Strichpunkt (;).                                                                        
                                                                                               
       Die Namen der Entities sind in ISO8879 definiert, die als Port textproc/iso8879         
       installiert werden kann.                                                                
                                                                                               
       Dazu einige Beispiele:                                                                  
                                                                                               
       Entity: &eacute;                                                                        
       Darstellung: e                                                                          
       Beschreibung: Kleines "e" mit (akutem) Akzent                                           
       Entity: &Eacute;                                                                        
       Darstellung: E                                                                          
       Beschreibung: Grosses "E" mit (akutem) Akzent                                           
       Entity: &uuml;                                                                          
       Darstellung: u:                                                                         
       Beschreibung: Kleines Umlaut-"u"                                                        
                                                                                               
       Nachdem Sie den iso8879-Port installiert haben, ist die vollsta:ndige Liste unter       
       /usr/local/share/xml/iso8879 vorhanden.                                                 
11.12. 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").                
11.13. Muss ich zusa:tzliche Informationen in meine U:bersetzungen einbauen?                   
       Ja.                                                                                     
                                                                                               
       Der Header der englischen Version jedes Textes sieht in etwa so aus:                    
                                                                                               
       <!--                                                                                    
            The FreeBSD Documentation Project                                                  
                                                                                               
            $FreeBSD: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z $     
                                                                                               
       Das exakte Aussehen kann unterschiedlich sein, die Zeile mit $FreeBSD$ sowie der        
       Ausdruck The FreeBSD Documentation Project sind allerdings immer enthalten. Beachten    
       Sie, dass die Zeile mit $FreeBSD von Subversion automatisch expandiert wird, daher      
       sollte an dieser Stelle in Ihren neuen Dokumenten nur $FreeBSD$ stehen.                 
                                                                                               
       Ihre u:bersetzten Dokumente sollten eine eigene $FreeBSD$-Zeile enthalten. Zusa:tzlich  
       sollten Sie die Zeile mit The FreeBSD Documentation Project in The FreeBSD              
       Ihre-Sprache-hier-einfu:gen Documentation Project.                                      
                                                                                               
       Ausserdem sollten Sie eine weitere Zeile einfu:gen, die festlegt, auf welcher Version   
       des englischen Originals Ihre U:bersetzung basiert.                                     
                                                                                               
       Die spanische Version dieser Datei ko:nnte etwa so beginnen:                            
                                                                                               
       <!--                                                                                    
            The FreeBSD Spanish Documentation Project                                          
                                                                                               
            $FreeBSD: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs $ 
            Original revision: r38674                                                          
       -->                                                                                     

                         Kapitel 12. PO-U:bersetzungen

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   12.1. Einfu:hrung

   12.2. Schnellstart

   12.3. Bisher nicht exisitierende Dokumente u:bersetzen

   12.4. U:bersetzen

   12.5. Tips fu:r U:bersetzer

   12.6. Ein u:bersetztes Dokument bauen

   12.7. Neue U:bersetzungen einreichen

12.1. Einfu:hrung

   Das GNU gettext-System bietet U:bersetzern eine einfache Mo:glichkeit,
   U:bersetzungen von Dokumenten zu erstellen und zu verwalten. U:bersetzbare
   Strings werden dabei aus dem Originaldokument extrahiert und in eine
   PO-Datei (Portable Object-Datei) gespeichert. U:bersetzte Versionen der
   Strings werden u:ber einen zusa:tzlichen Editor eingefu:gt. Diese Strings
   ko:nnen danach direkt verwendet werden oder zu einer kompletten
   U:bersetzung des Originaldokuments zusammengefu:gt werden.

12.2. Schnellstart

   Die Anleitung geht davon aus, das sie die Anweisungen in Abschnitt 1.2,
   "Schnellstart" bereits ausgefu:hrt haben, allerdings mu:ssen Sie noch
   zusa:tzlich die Option TRANSLATOR im Port textproc/docproj aktivieren. War
   diese Option bisher nicht aktiviert, o:ffnen Sie jetzt die Konfiguration,
   aktivieren die Option und bauen den Port anschliessend neu.

 # cd /usr/ports/textproc/docproj
 # make config
 # make clean deinstall install clean

   Das folgende Beispiel zeigt, wie Sie den kurzen Artikel Leap Seconds auf
   Spanisch u:bersetzen.

   Prozedur 12.1. Installieren Sie einen PO-Editor
     * Sie beno:tigen einen PO-Editor, um die U:bersetzungsdateien zu
       bearbeiten. Dieses Beispiel verwendet dafu:r editors/poedit.

 # cd /usr/ports/editors/poedit
 # make install clean

   Prozedur 12.2. Grundkonfiguration

   Wenn Sie mit der Arbeit an einer bisher nicht existierenden Sprache oder
   einem nicht existierenden Dokument beginnen wollen, mu:ssen Sie zuerst die
   Verzeichnisstruktur und ein Makefile anlegen oder von der englischen
   Originalversion kopieren:

    1. Legen Sie ein Verzeichnis fu:r die neue U:bersetzung an. Der Quellcode
       des englischen Artikel befindet sich unter
       ~/doc/en_US.ISO8859-1/articles/leap-seconds/. Die spanische
       U:bersetzung muss daher im Verzeichnis
       ~/doc/es_ES.ISO8859-1/articles/leap-seconds/ erstellt werden. Der Pfad
       ist also (abgesehen vom sprachspezifischen Verzeichnis) identisch.

 % svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/

    2. Kopieren Sie das Makefile des Originaldokuments in das
       U:bersetzungsverzeichnis:

 % svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \
     ~/doc/es_ES.ISO8859-1/articles/leap-seconds/

   Prozedur 12.3. U:bersetzung

   Das U:bersetzen eines Dokuments erfolgt in zwei Schritten, zuerst werden
   die zu u:bersetzenden Strings aus dem Originaldokument extrahiert, um sie
   anschliessend zu u:bersetzen. Diese beiden Schritte werden wiederholt, bis
   ein brauchbares u:bersetztes Dokument entstanden ist.

    1. Extrahieren Sie die zu u:bersetzenden Strings aus der originalen
       englischen Version und speichern Sie diese in einer PO-Datei:

 % cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
 % make po

    2. Verwenden Sie einen PO-Editor, um Ihre U:bersetzungen in der PO-Datei
       zu speichern. Dafu:r gibt es diverse Editoren, dieses Beispiel
       verwendet poedit (das Sie u:ber den Port editors/poedit installieren
       ko:nnen).

       Der Name der PO-Datei setzt sich aus einem zwei Zeichen langen
       Sprachcode, gefolgt von einem Unterstrich sowie einem ebenfalls zwei
       Zeichen langen Regionencode zusammen. Fu:r eine U:bersetzung ins
       Spanische heisst die Datei daher es_ES.po.

 % poedit es_ES.po

   Prozedur 12.4. Ein u:bersetztes Dokument bauen
    1. Bauen Sie das u:bersetzte Dokument:

 % cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
 % make tran

       Der Name der erzeugten Datei entspricht dem Namen der englischen
       Originaldatei, normalerweise also article.xml fu:r Artikel oder
       book.xml fu:r Bu:cher.

    2. U:berpru:fen Sie die gebaute Datei, indem Sie sie in HTML bauen und in
       einem Internetbrowser o:ffnen:

 % make FORMATS=html
 % firefox article.html

12.3. Bisher nicht exisitierende Dokumente u:bersetzen

   Der erste Schritt, um ein neues Dokument zu u:bersetzen, besteht darin,
   ein Verzeichnis zu suchen oder zu erstellen, in dem die U:bersetzung
   gespeichert werden soll. FreeBSD legt alle u:bersetzten Dokumente in einem
   Unterverzeichnis ab, dessen Name sich aus der Sprache und aus der Region
   in der Form lang_REGION zusammensetzt. lang ist ein Code, der immer aus
   zwei Zeichen in Kleinbuchstaben besteht. Auf ihn folgt ein Unterstrich und
   danach der Code fu:r die REGION (der aus zwei Zeichen in Grossbuchstaben
   besteht).

   Tabelle 12.1. Existierende Sprachen

     Sprache       Region    U:bersetzungsverzeichnis PODateiname Zeichensatz 
                Vereinigte                                                    
   Englisch     Staaten von  en_US.ISO8859-1          en_US.po    ISO 8859-1
                Amerika      
   Bengalisch   Bangladesch  bn_BD.UTF-8              bn_BD.po    UTF-8       
   Da:nisch     Da:nemark    da_DK.ISO8859-1          da_DK.po    ISO 8859-1  
   Deutsch      Deutschland  de_DE.ISO8859-1          de_DE.po    ISO 8859-1  
   Griechisch   Griechenland el_GR.ISO8859-7          el_GR.po    ISO 8859-7  
   Spanisch     Spanien      es_ES.ISO8859-1          es_ES.po    ISO 8859-1  
   French       France       fr_FR.ISO8859-1          fr_FR.po    ISO 8859-1  
   Ungarisch    Ungarn       hu_HU.ISO8859-2          hu_HU.po    ISO 8859-2  
   Italienisch  Italien      it_IT.ISO8859-15         it_IT.po    ISO 8859-15 
   Japanisch    Japan        ja_JP.eucJP              ja_JP.po    EUC JP      
   Koreanisch   Korea        ko_KR.UTF-8              ko_KR.po    UTF-8       
   Mongolisch   Mongolien    mn_MN.UTF-8              mn_MN.po    UTF-8       
   Holla:ndisch Niederlande  nl_NL.ISO8859-1          nl_NL.po    ISO 8859-1  
   Norwegisch   Norwegen     no_NO.ISO8859-1          no_NO.po    ISO 8859-1  
   Polnisch     Polen        pl_PL.ISO8859-2          pl_PL.po    ISO 8859-2  
   Portugisisch Brasilien    pt_BR.ISO8859-1          pt_BR.po    ISO 8859-1  
   Russisch     Russland     ru_RU.KOI8-R             ru_RU.po    KOI8-R      
   Serbisch     Serbien      sr_YU.ISO8859-2          sr_YU.po    ISO 8859-2  
   Tu:rkisch    Tu:rkei      tr_TR.ISO8859-9          tr_TR.po    ISO 8859-9  
   Chinesisch   China        zh_CN.UTF-8              zh_CN.po    UTF-8       
   Chinesisch   Taiwan       zh_TW.UTF-8              zh_TW.po    UTF-8       

   Die U:bersetzungen befinden sich in Unterverzeichnissen des
   Hauptverzeichnisses der Dokumentation (in den Beispielen von
   Abschnitt 1.2, "Schnellstart" ist dies ~/doc/). Die deutschen
   U:bersetzungen befinden sich daher beispielsweise unter
   ~/doc/de_DE.ISO8859-1/, franzo:sische U:bersetzungen hingegen unter
   ~/doc/fr_FR.ISO8859-1/.

   Jede Sprache entha:lt Unterverzeichnisse fu:r die verschiedenen
   Dokumenttypen, also u:blicherweise articles/ und books/.

   Kombiniert man diese Verzeichnisnamen, erha:lt man den kompletten Pfad zu
   einem Artikel oder zu einem Buch. Die franzo:sische U:bersetzung des
   NanoBSD-Artikels ist daher etwa unter
   ~/doc/fr_FR.ISO8859-1/articles/nanobsd/ gespeichert, die mongolische
   U:bersetzung des Handbuchs hingegen unter
   ~/doc/mn_MN.UTF-8/books/handbook/.

   Soll ein Dokument in eine bisher nicht existierende Sprache u:bersetzt
   werden, muss zuerst ein sprachspezifisches Verzeichnis erstellt werden.
   Existiert die Sprache hingegen schon, muss nur ein Unterverzeichnis
   unterhalb von articles/ oder books/ angelegt werden (falls noch nicht
   vorhanden).

   Der Bau der FreeBSD-Dokumentation wird durch ein Makefile gesteuert, das
   sich im gleichen Verzeichnis wie die U:bersetzung befindet. Fu:r einfache
   Artikel kann dieses Makefile oft unvera:ndert aus der englischen
   Originalversion u:bernommen werden. Der U:bersetzungsprozess fu:r Bu:cher
   ist hingegen komplizierter, da dabei verschiedene getrennte book.xml und
   chapter.xml-Dateien in ein gemeinsames Dokument integriert werden, das
   Makefile fu:r die U:bersetzung eines Buches muss daher in der Regel immer
   kopiert und angepasst werden.

   Beispiel 12.1. Die spanische U:bersetzung des Porter's Handbook erstellen

   Starten Sie die bisher nicht vorhandene spanische U:bersetzung des
   Porter's Handbook. Das originale Dokument ist ein Buch im Verzeichnis
   ~/doc/en_US.ISO8859-1/books/porters-handbook/.

    1. Das Verzeichnis fu:r die spanische U:bersetzung
       (~/doc/es_ES.ISO8859-1/books/) existiert bereits, daher mu:ssen Sie
       nur ein Unterverzeichnis fu:r das Porter's Handbook anlegen:

 % cd ~/doc/es_ES.ISO8859-1/books/
 % svn mkdir porters-handbook
 A         porters-handbook

    2. Kopieren Sie das Makefile des Originalen Buchs in den neuen Ordner:

 % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
 % svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .
 A         Makefile

       Passen Sie das Makefile an, damit es nur eine einzige book.xml als
       Eingabe erwartet:

 #
 # $FreeBSD$
 #
 # Build the FreeBSD Porter's Handbook.
 #

 MAINTAINER=doc@FreeBSD.org

 DOC?= book

 FORMATS?= html-split

 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=

 # XML content
 SRCS=  book.xml

 # Images from the cross-document image library
 IMAGES_LIB+=    callouts/1.png
 IMAGES_LIB+=    callouts/2.png
 IMAGES_LIB+=    callouts/3.png
 IMAGES_LIB+=    callouts/4.png
 IMAGES_LIB+=    callouts/5.png
 IMAGES_LIB+=    callouts/6.png
 IMAGES_LIB+=    callouts/7.png
 IMAGES_LIB+=    callouts/8.png
 IMAGES_LIB+=    callouts/9.png
 IMAGES_LIB+=    callouts/10.png
 IMAGES_LIB+=    callouts/11.png
 IMAGES_LIB+=    callouts/12.png
 IMAGES_LIB+=    callouts/13.png
 IMAGES_LIB+=    callouts/14.png
 IMAGES_LIB+=    callouts/15.png
 IMAGES_LIB+=    callouts/16.png
 IMAGES_LIB+=    callouts/17.png
 IMAGES_LIB+=    callouts/18.png
 IMAGES_LIB+=    callouts/19.png
 IMAGES_LIB+=    callouts/20.png
 IMAGES_LIB+=    callouts/21.png

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

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

       Damit steht die Dokumentstruktur bereit und Sie ko:nnen die PO-Datei
       mit make po erstellen.

   Beispiel 12.2. Die franzo:sische U:bersetzung des PGP Keys-Artikels
   erstellen

   Starten Sie die bisher nicht vorhandene U:bersetzung des PGP
   Keys-Artikels. Das englische Original ist ein Artikel, der sich im
   Verzeichnis ~/doc/en_US.ISO8859-1/articles/pgpkeys/ befindet.

    1. Das Verzeichnis fu:r franzo:sische Artikel
       (~/doc/fr_FR.ISO8859-1/articles/) existiert bereits, Sie mu:ssen daher
       nur ein neues Unterverzeichnis fu:r den PGP Keys-Artikel anlegen:

 % cd ~/doc/fr_FR.ISO8859-1/articles/
 % svn mkdir pgpkeys
 A         pgpkeys

    2. Kopieren Sie das Makefile des originalen Artikels:

 % cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys
 % svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .
 A         Makefile

       U:berpru:fen Sie das Makefile. Da es sich um einen einfachen Artikel
       handelt, sind vermutlich keine A:nderungen am Makefile no:tig. Der
       Inhalt der zweiten Zeile ($FreeBSD...$) wird durch das
       Versionskontrollsystem ersetzt werden, wenn diese Datei committet
       wird.

 #
 # $FreeBSD$
 #
 # Article: PGP Keys

 DOC?= article

 FORMATS?= html
 WITH_ARTICLE_TOC?= YES

 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=

 SRCS=   article.xml

 # To build with just key fingerprints, set FINGERPRINTS_ONLY.

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

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

       Damit steht die Dokumentstruktur bereit und Sie ko:nnen die PO-Datei
       mit make po erstellen.

12.4. U:bersetzen

   Das gettext-System macht die U:bersetzung von Dokumenten einfacher, weil
   sich der U:bersetzer dadurch um weniger Dinge ku:mmern muss. Die zu
   u:bersetzenden Strings werden aus dem Originaldokument in eine PO-Datei
   extrahiert. Danach wird ein PO-Editor verwendet, um die u:bersetzten
   Strings einzugeben.

   Das von FreeBSD verwendete PO-U:bersetzungssystem u:berschreibt PO-Dateien
   nicht, daher ko:nnen die Strings jederzeit extrahiert werden, um die
   PO-Datei zu aktualisieren.

   Ein PO-Editor wird zum Bearbeiten der Datei beno:tigt. Die Beispiele in
   diesem Abschnitt verwenden editors/poedit, da es sich dabei um einen
   einfach zu bedienenden Editor mit nur wenigen Abha:ngigkeiten handelt. Es
   gibt aber auch diverse andere PO-Editoren, die zusa:tzliche Funktionen
   haben, die bei der U:bersetzung von Dokumenten helfen. Die Ports-Sammlung
   entha:lt verschiedene dieser Editoren, beispielsweise devel/gtranslator.

   Lo:schen Sie die PO-Datei auf keinen Fall, da Sie alle A:nderungen
   entha:lt, die U:bersetzer vorgenommen haben.

   Beispiel 12.3. Die spanische Version des Porter's Handbook u:bersetzen

   Beginnen Sie mit der U:bersetzung des spanischen Porter's Handbook.

    1. Wechseln Sie in das Verzeichnis des spanischen Porter's Handbook und
       aktualisieren Sie die PO-Datei (wie bereits in Tabelle 12.1,
       "Existierende Sprachen" erwa:hnt, heisst diese Datei es_ES.po.

 % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
 % make po

    2. Laden Sie die Datei in Ihren PO-Editor und beginnen Sie mit der
       U:bersetzung:

 % poedit es_ES.po

12.5. Tips fu:r U:bersetzer

  12.5.1. XML-Tags beibehalten

   Achten Sie darauf, dass Sie keine XML-Tags des englischen Originals
   vera:ndern.

   Beispiel 12.4. XML-Tags beibehalten

   Englisches Original:

 If <acronym>NTP</acronym> is not being used

   Spanische U:bersetzung:

 Si <acronym>NTP</acronym> no se utiliza

  12.5.2. Leerzeichen beibehalten

   Achten Sie darauf, dass Sie Leerzeichen am Beginn und am Ende der zu
   u:bersetzenden Strings beibehalten. Ihre U:bersetzung muss diese Strings
   ebenfalls enthalten.

  12.5.3. Nicht zu u:bersetzende Tags

   Die folgenden Tags du:rfen nicht u:bersetzt werden:

     * <citerefentry>

     * <command>

     * <filename>

     * <literal>

     * <manvolnum>

     * <orgname>

     * <package>

     * <programlisting>

     * <prompt>

     * <refentrytitle>

     * <screen>

     * <userinput>

     * <varname>

  12.5.4. $FreeBSD$-Strings

   $FreeBSD$-Versionsstrings erfordern eine spezielle Behandlung. In
   Codebeispielen wie in Beispiel 12.1, "Die spanische U:bersetzung des
   Porter's Handbook erstellen" sollen diese Strings NICHT expandiert werden.
   Englische Dokumente verwenden deshalb die Entita:t &dollar;, damit das
   Dollarzeichen nicht in die Datei eingefu:gt werden muss:

 &dollar;FreeBSD&dollar;

   Die Entita:t &dollar; wird vom Versionskontrollsystem nicht als
   Dollarzeichen interpretiert und daher auch nicht in einen Versionsstring
   expandiert.

   Wenn Sie eine PO-Datei erzeugen, wird die Entita:t &dollar; allerdings
   wieder durch das aktuelle Dollarzeichen ersetzt. Dies fu:hrt dazu, dass
   der dadurch enstandene String $FreeBSD$ beim Commit im
   Versionskontrollsystem fa:lschlicherweise wieder expandiert wird.

   Gehen Sie daher analog zum englischen Originaldokument vor und ersetzen
   Sie das Dollarzeichen in der u:bersetzten PO-Datei wiederum durch die
   Entita:t &dollar;:

 &dollar;FreeBSD&dollar;

12.6. Ein u:bersetztes Dokument bauen

   Eine u:bersetzte Version eines Originaldokuments kann jederzeit erzeugt
   werden. Noch nicht u:bersetzte Teile des Dokuments werden dabei in
   Englisch verbleiben. Die meisten PO-Editoren zeigen Ihnen an, welcher
   Anteil des Dokuments bereits u:bersetzt ist. Dies erleichtert es dem
   U:bersetzer zu beurteilen, ob sich der Bau des finalen Dokuments bereits
   lohnt oder nicht.

   Beispiel 12.5. Die spanische Version des Porter's Handbook bauen

   Bauen Sie die spanische Version des Porter's Handbooks, das in einem
   fru:heren Beispiel erzeugt wurde und u:berpru:fen Sie das Ergebnis.

    1. Bauen Sie das Dokument. Da das Original vom Typ Buch (book) ist,
       heisst das erzeugte Dokument book.xml.

 % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
 % make tran

    2. Erzeugen Sie aus der book.xml eine HTML-Version des Dokuments und
       lassen Sie sich das Ergebnis in Firefox anzeigen. Fu:r die englische
       Dokumentation gehen Sie analog vor. Eine Liste aller verfu:gbaren
       Werte fu:r die Variable FORMATS finden Sie in Tabelle 5.1, "Ha:ufige
       Ausgabeformate".

 % make FORMATS=html
 % firefox book.html

12.7. Neue U:bersetzungen einreichen

   Die neue U:bersetzung ist nun zum Einreichen bereit. Um eine neue
   U:bersetzung einzureichen, mu:ssen Sie die neuen U:bersetzungen in das
   Versionskontrollsystem einfu:gen, die Dateieigenschaften anpassen und eine
   Differenz erstellen, die Sie dann einreichen ko:nnen.

   Die in den folgenden Beispielen erstellten Differenzen ko:nnen Sie
   entweder als Documentation Bug Report oder als Code Review einreichen.

   Beispiel 12.6. Die Spanische U:bersetzung des NanoBSD-Artikel
    1. Fu:gen Sie in die PO-Datei als erste Zeile einen Kommentar mit dem
       FreeBSD-Versionsstring ein:

 #$FreeBSD$

    2. Nehmen Sie das Makefile, die PO-Datei und die erzeugte
       XML-U:bersetzung in die Versionskontrolle auf:

 % cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/
 % ls
 Makefile        article.xml     es_ES.po
 % svn add Makefile article.xml es_ES.po
 A         Makefile
 A         article.xml
 A         es_ES.po

    3. Setzen Sie die Subversion-Eigenschaft svn:keywords auf FreeBSD=%H.
       Diese Eigenschaft sorgt spa:ter beim Commit dafu:r, dass der String
       $FreeBSD$ erweitert wird und den Pfad, die Revision, das Datum und den
       Autor des Committs entha:lt:

 % svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po
 property 'svn:keywords' set on 'Makefile'
 property 'svn:keywords' set on 'article.xml'
 property 'svn:keywords' set on 'es_ES.po'

    4. Setzen Sie den korrekten MIME-Typ fu:r die neuen Dateien. Fu:r Bu:cher
       und Artikel ist dies text/xml, fu:r die PO-Datei hingegen
       text/x-gettext-translation.

 % svn propset svn:mime-type text/x-gettext-translation es_ES.po
 property 'svn:mime-type' set on 'es_ES.po'
 % svn propset svn:mime-type text/xml article.xml
 property 'svn:mime-type' set on 'article.xml'

    5. Wechseln Sie nach ~/doc/ und erstellen Sie aus diesem Basisverzeichnis
       eine Differenz, damit der komplette Pfad in der Differenz angezeigt
       wird. Dies erleichert es Committern, das korrekte Zielverzeichnis zu
       identifizieren:

 % cd ~/doc
 svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff

   Beispiel 12.7. Koreanische UTF-8-U:bersetzung des Explaining-BSD-Artikels
    1. Fu:gen Sie in die PO-Datei als erste Zeile einen Kommentar mit dem
       FreeBSD-Versionsstring ein:

 #$FreeBSD$

    2. Nehmen Sie das Makefile, die PO-Datei und die erzeugte
       XML-U:bersetzung in die Versionskontrolle auf:

 % cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/
 % ls
 Makefile        article.xml     ko_KR.po
 % svn add Makefile article.xml ko_KR.po
 A         Makefile
 A         article.xml
 A         ko_KR.po

    3. Setzen Sie die Subversion-Eigenschaft svn:keywords auf FreeBSD=%H.
       Diese Eigenschaft sorgt spa:ter beim Commit dafu:r, dass der String
       $FreeBSD$ erweitert wird und den Pfad, die Revision, das Datum und den
       Autor des Committs entha:lt:

 % svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po
 property 'svn:keywords' set on 'Makefile'
 property 'svn:keywords' set on 'article.xml'
 property 'svn:keywords' set on 'ko_KR.po'

    4. Setzen Sie den korrekten MIME-Typ fu:r alle Dateien. Da die Dateien
       mit dem UTF-8-Charakterset erstellt wurden, muss dies ebenfalls
       angegeben werden. Um zu verhindern, dass das Versionskontrollsystem
       diese Dateien als Bina:rdateien erkennt, mu:ssen Sie die Eigenschaft
       fbsd:notbinary setzen:

 % svn propset svn:mime-type 'text/x-gettext-translation; charset=UTF-8' ko_KR.po
 property 'svn:mime-type' set on 'ko_KR.po'
 % svn propset fbsd:notbinary yes ko_KR.po
 property 'fbsd:notbinary' set on 'ko_KR.po'
 % svn propset svn:mime-type 'text/xml; charset=UTF-8' article.xml
 property 'svn:mime-type' set on 'article.xml'
 % svn propset fbsd:notbinary yes article.xml
 property 'fbsd:notbinary' set on 'article.xml'

    5. Wechseln Sie nach ~/doc/ und erstellen Sie aus diesem Basisverzeichnis
       eine Differenz, damit der komplette Pfad in der Differenz angezeigt
       wird. Dies erleichert es Committern, das korrekte Zielverzeichnis zu
       identifizieren:

 % cd ~/doc
 svn diff ko_KR.UTF-8/articles/explaining-bsd > /tmp/ko-explaining.diff

                          Kapitel 13. Der Schreibstil

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   13.1. Anleitungen fu:r einen korrekten Schreibstil

   13.2. Ha:ufig verwendete Wo:rter

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

   Verwendung von amerikanischem Englisch

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

  Anmerkung:

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

   Vermeiden von Zusammenziehungen

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

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

   Nutzung von Kommas bei Aufza:hlungen

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

           Dazu ein Beispiel:

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

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

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

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

   Vermeidung von redundanten Begriffen

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

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

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

           Verwenden Sie svn, um Ihre Quellen zu aktualisieren.

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

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

           ... in /etc/rc.local...

           Auch fu:r Manualpages gibt es zwei Schreibweisen. Auch hier wird
           die zweite Schreibweise bevorzugt (das zweite Beispiel nutzt das
           Tag citerefentry).

           Weitere Informationen finden Sie in man csh.

           Weitere Informationen finden Sie in csh(1).

   Zwei Leerzeichen am Satzende

           Verwenden Sie immer zwei Leerzeichen am Ende eines Satzes. Dadurch
           erho:ht sich die Lesbarkeit des Textes und die Nutzung von
           Werkzeugen wie Emacs wird vereinfacht.

           Nun ko:nnte man behaupten, dass ein Punkt vor einem
           Grossbuchstaben das Satzende markiert. Vor allem bei Namen,
           beispielsweise bei "Jordan K. Hubbard", ist dies allerdings nicht
           der Fall. Wir haben hier ein grosses K, gefolgt von einem Punkt
           und einem Leerzeichen. Dennoch handelt es sich nicht um den Anfang
           eines neuen Satzes.

   Eine ausfu:hrliche Beschreibung des korrekten Schreibstils finden Sie im
   Buch Elements of Style von William Strunk.

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

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

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

  13.1.3. Einru:ckung

   Die erste Zeile jeder Datei hat die Einru:ckung 0, und zwar unabha:ngig
   von der Einru:ckung der Datei, in der sie enthalten ist.

   O:ffnende Tags erho:hen die Einru:ckung um zwei Leerzeichen. Schliessende
   Tags verringern sie hingegen um zwei Leerzeichen. Ein Block von acht
   Leerzeichen wird durch einen Tabulator ersetzt. Ein solcher Block beginnt
   immer am Anfang einer Zeile, fu:hrende Leerzeichen sind hier also nicht
   erlaubt. Vermeiden Sie ausserdem Leerzeichen am Zeilenende. Der Inhalt von
   Elementen wird um zwei Leerzeichen eingeru:ckt, wenn er sich u:ber mehr
   als eine Zeile erstreckt.

   Der Quellcode dieses Abschnitts sieht daher in etwa so aus:

 +--- Einru:ckung (Spalte) 0
 V
 <chapter>
   <title>...</title>

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

     <sect2>
       <title>Einru:ckung</title>

       <para>Die erste Zeile jeder Datei hat die Einru:ckung 0, und
         zwar <emphasis>unabha:ngig</emphasis> von der Einru:ckung
         der Datei, in der sie enthalten ist.</para>

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

   Wenn Sie Emacs oder XEmacs verwenden, um Ihre Dateien zu bearbeiten,
   sollte der sgml-mode automatisch geladen werden, und die lokalen
   Emacs-Variablen am Ende einer Datei sollten diesen Stil erzwingen.

   Verwenden Sie Vim, sollten Sie Ihren Editor so konfigurieren:

 augroup sgmledit
   autocmd FileType sgml set formatoptions=cq2l " Special formatting options
   autocmd FileType sgml set textwidth=70       " Wrap lines at 70 columns
   autocmd FileType sgml set shiftwidth=2       " Automatically indent
   autocmd FileType sgml set softtabstop=2      " Tab key indents 2 spaces
   autocmd FileType sgml set tabstop=8          " Replace 8 spaces with a tab
   autocmd FileType sgml set autoindent         " Automatic indentation
 augroup END

  13.1.4. Die korrekte Schreibweise von Tags

    13.1.4.1. Einru:cken von Tags

   Tags, die die gleiche Einru:ckung aufweisen wie das vorangegangene Tag,
   sollten durch eine Leerzeile getrennt werden, Tags mit unterschiedlicher
   Einru:ckung hingegen nicht:

 <article lang='de'>
   <articleinfo>
     <title>NIS</title>

     <pubdate>October 1999</pubdate>

     <abstract>
       <para>...
         ...
         ...</para>
     </abstract>
   </articleinfo>

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

     <para>...</para>
   </sect1>

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

     <para>...</para>
   </sect1>
 </article>

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

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

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

13.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 14. Editor-Konfiguration

   U:bersetzt von Johann Kois.
   Inhaltsverzeichnis

   14.1. Vim

   14.2. Emacs

   14.3. nano

   Die korrekte Konfiguration Ihres Texteditors macht die Arbeit an der
   Dokumentation einfacher und schneller und hilft Ihnen dabei, die
   FDP-Richtlinien einzuhalten.

14.1. Vim

   Installieren Sie entweder das Paket editors/vim oder editors/vim-lite,
   danach folgen Sie den Anweisungen in Abschnitt 14.1.2, "Konfiguration".

  14.1.1. Verwendung

   Dru:cken Sie die Taste P, um Absa:tze oder Text, den Sie im visuellen
   Modus ausgewa:hlt haben, zu formatieren. Dru:cken Sie die Taste T, um 8
   Leerzeichen durch einen Tabulator zu ersetzen.

  14.1.2. Konfiguration

   Fu:gen Sie die folgenden Zeilen am Ende der Datei ~/.vimrc ein:

 if has("autocmd")
     au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML()
     au BufNewFile,BufRead *.[1-9] call ShowSpecial()
 endif " has(autocmd)

 function Set_Highlights()
     "match ExtraWhitespace /^\s* \s*\|\s\+$/
     highlight default link OverLength ErrorMsg
     match OverLength /\%71v.\+/
     return 0
 endfunction

 function ShowSpecial()
     setlocal list listchars=tab:>>,trail:*,eol:$
     hi def link nontext ErrorMsg
     return 0
 endfunction " ShowSpecial()

 function Set_SGML()
     setlocal number
     syn match sgmlSpecial "&[^;]*;"
     setlocal syntax=sgml
     setlocal filetype=xml
     setlocal shiftwidth=2
     setlocal textwidth=70
     setlocal tabstop=8
     setlocal softtabstop=2
     setlocal formatprg="fmt -p"
     setlocal autoindent
     setlocal smartindent
     " Rewrap paragraphs
     noremap P gqj
     " Replace spaces with tabs
     noremap T :s/        /\t/<CR>
     call ShowSpecial()
     call Set_Highlights()
     return 0
 endfunction " Set_SGML()

14.2. Emacs

   Installieren Sie entweder das Paket editors/emacs oder
   editors/emacs-devel.

  14.2.1. Validierung

   Der xnml-Modus von Emacs verwendet ein kompaktes RELAX-NG ("Regular
   Language Description for XML New Generation")-Schema, um XML zu
   validieren. Ein solches, an DocBook 5.0 von FreeBSD angepasstes Schema ist
   im Dokumentationsrepository bereits vorhanden. Damit der nxml-Modus dieses
   Schema verwendet, mu:ssen Sie die Datei ~/.emacs.d/schema/schemas.xml
   anlegen und folgende Zeilen in die Datei einfu:gen:

 <locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
   <documentElement localName="section" typeId="DocBook">
   <documentElement localName="chapter" typeId="DocBook">
   <documentElement localName="article" typeId="DocBook">
   <documentElement localName="book" typeId="DocBook">
   <typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc">
 </locatingRules>

  14.2.2. Automatisches Gegenlesen mit Flycheck und Igor

   Das Flycheck-Paket ist u:ber "Milkypostman's Emacs Lisp Package Archive"
   (MELPA) erha:ltlich. Ist MELPA noch nicht in packages-archives von Emacs
   eingetragen, muss dies manuell durch das Ausfu:hren der folgenden
   Emacs-Anweisung erfolgen:

 (add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)

   Um die A:nderung permanent zu machen, mu:ssen Sie diese Zeile in die
   Initialisierungsdatei von Emacs aufnehmen, konkret in eine der folgenden
   Dateien: ~/.emacs, ~/.emacs.el oder ~.emacs.d/init.el.

   Um Flycheck zu installieren, fu:hren Sie folgende Anweisung aus:

 (package-install 'flycheck)

   Legen Sie einen Flycheck-Pru:fer fu:r textproc/igor an, indem Sie die
   folgende Anweisung ausfu:hren:

 (flycheck-define-checker igor
   "FreeBSD Documentation Project sanity checker.

 See URLs http://www.freebsd.org/docproj/ and
 http://www.freshports.org/textproc/igor/."
   :command ("igor" "-X" source-inplace)
   :error-parser flycheck-parse-checkstyle
   :modes (nxml-mode)
   :standard-input t)

   (add-to-list 'flycheck-checkers 'igor 'append)

   Wie bei MELPA mu:ssen Sie auch diese Anweisung in die
   Initialisierungsdatei von Emacs aufnehmen, um sie permanent zu aktivieren.

  14.2.3. FreeBSD-Dokumentationsspezische Einstellungen

   Um FreeBSD-spezifische Einstellungen zu aktivieren, legen Sie die Datei
   .dir-locals.el im Wurzelverzeichnis des Dokumentationsrepositories an und
   fu:gen die folgenden Zeilen in diese Datei ein:

 ;;; Directory Local Variables
 ;;; For more information see (info "(emacs) Directory Variables")

 ((nxml-mode
   (eval . (turn-on-auto-fill))
   (fill-column . 70)
   (eval . (require 'flycheck))
   (eval . (flycheck-mode 1))
   (flycheck-checker . igor)
   (eval . (add-to-list 'rng-schema-locating-files "~/.emacs.d/schema/schemas.xml"))))

14.3. nano

   Installieren Sie das Paket editors/nano oder editors/nano-devel.

  14.3.1. Konfiguration

   Kopieren Sie die Syntaxhighlighting-Datei fu:r XML in ihr Homeverzeichnis:

 % cp /usr/local/share/nano/xml.nanorc ~/.nanorc

   Fu:gen Sie die folgenden Zeilen in die Datei ~/.nanorc ein:

 syntax "xml" "\.([jrs]html?|xml|xslt?)$"
 # trailing whitespace
 color ,blue "[[:space:]]+$"
 # multiples of eight spaces at the start a line
 # (after zero or more tabs) should be a tab
 color ,blue "^([TAB]*[ ]{8})+"
 # tabs after spaces
 color ,yellow "( )+TAB"
 # highlight indents that have an odd number of spaces
 color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}"
 # lines longer than 70 characters
 color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"

   Verarbeiten Sie diese Datei, um eingebettete Tabulatoren zu erzeugen:

 % perl -i'' -pe 's/TAB/\t/g' ~/.nanorc

  14.3.2. Verwendung

   Starten Sie Nano mit zusa:tzlichen hilfreichen Parametern:

 % nano -AKipwz -r 70 -T8 chapter.xml

   Verwenden Sie csh(1), ko:nnen Sie in ~/.cshrc einen Alias fu:r diese
   Parameter anlegen:

 alias nano "nano -AKipwz -r 70 -T8"

   Nachdem der Alias definiert wurde, werden diese Parameter ku:nftig
   automatisch angewendet:

 % nano chapter.xml

                      Kapitel 15. Weiterfu:hrende Quellen

   Inhaltsverzeichnis

   15.1. Das FreeBSD-Dokumentationsprojekt

   15.2. XML

   15.3. HTML

   15.4. DocBook

   15.5. Das Linux-Dokumentationsprojekt

   In dieser Fibel werden absichtlich nicht alle Aspekte von XML, der
   erwa:hnten DTDs und des FreeBSD-Dokumentationsprojekts behandelt.
   Interessierten werden daher die nachfolgenden Quellen empfohlen.

15.1. Das FreeBSD-Dokumentationsprojekt

     * Die Webseiten des FreeBSD-Dokumentationsprojektes

     * Das FreeBSD-Handbuch

15.2. XML

     * W3C's XML-Webseite, eine umfangreiche Quelle zu XML.

15.3. HTML

     * Das World-Wide-Web-Konsortium

     * Die HTML 4.0-Spezifikation

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

15.5. Das Linux-Dokumentationsprojekt

     * Die Webseiten des Linux-Dokumenationsprojektes.

                              Anhang A. Beispiele

   Inhaltsverzeichnis

   A.1. DocBook-Buch (book)

   A.2. DocBook-Artikel (article)

   A.3. Ausgabeformate erzeugen

   In diesem Anhang sind XML-Beispieldokumente und Befehle enthalten, die
   zeigen, wie man aus DocBook-Dokumenten verschiedene Ausgabeformate
   erzeugen kann. Sofern alle Werkzeuge fu:r das Dokumentationsprojekt
   ordnungsgema:ss installiert wurden, ko:nnen die angebotenen Beispiele
   direkt u:bernommen werden.

   Die Beispiele dieses Abschnitts sind bewusst einfach aufgebaut. Daher
   fehlen in den Beispielen einige Elemente, insbesondere Elemente fu:r die
   Titelei. Weitere DocBook-Beispiele ko:nnen in den DocBook-Quellen dieses
   und anderer Dokumente des FDPs gefunden werden. Die Quellen des FDPs sind
   im svn doc-Repository und online unter http://svnweb.FreeBSD.org/doc/
   verfu:gbar.

   Um Irritationen zu vermeiden, bauen die XML-Beispiele auf der 4.1er
   Standard-DocBook DTD anstatt auf der erweiterten FreeBSD-Variante auf.
   Ebenso werden die Standardstylesheets von Norman Welsh, anstatt der
   angepassten Stylesheets des FreeBSD-Dokumentationsprojektes benutzt.
   Dadurch eignen sich die Beispiele auch als generische DocBook-Vorlagen.

A.1. DocBook-Buch (book)

   Beispiel A.1. Ein DocBook-Buch (book)

 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

 <book lang='de'>
   <bookinfo>
     <title>Ein Buchbeispiel</title>

     <author>
       <firstname>Vorname</firstname>
       <surname>Nachname</surname>
       <affiliation>
         <address><email>vorname.nachname@domain.de</email></address>
       </affiliation>
     </author>

     <copyright>
       <year>2000</year>
       <holder>Urheberhinweis</holder>
     </copyright>

     <abstract>
       <para>Falls das Buch eine Zusammenfassung hat, sollte sie
         hier stehen.</para>
     </abstract>
   </bookinfo>

   <preface>
     <title>Einleitung</title>

     <para>Falls das Buch eine Einleitung hat, sollte diese hier
       stehen.</para>
   </preface>

   <chapter>
     <title>Das erste Kapitel</title>

     <para>Das ist das erste Kapitel des Buches.</para>

     <sect1>
       <title>Der erste Abschnitt</title>

       <para>Das ist der erste Abschnitte des Buches.</para>
     </sect1>
   </chapter>
 </book>

A.2. DocBook-Artikel (article)

   Beispiel A.2. Ein DocBook-Artikel (article)

 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

 <article lang='de'>
   <articleinfo>
     <title>Ein Beispielartikel</title>

     <author>
       <firstname>Vorname</firstname>
       <surname>Nachname</surname>
       <affiliation>
         <address><email>vorname.nachname@domain.de</email></address>
       </affiliation>
     </author>

     <copyright>
       <year>2000</year>
       <holder>Urheberhinweis</holder>
     </copyright>

     <abstract>
       <para>Falls der Artikel eine Zusammenfassung hat, sollte sie
         hier stehen.</programlisting>
     </abstract>
   </articleinfo>

   <sect1>
     <title>Der erste Abschnitt</title>

     <para>Das ist der erste Abschnitt des Artikels.</para>

     <sect2>
       <title>Der erste Unterabschnitt</title>

       <para>Das ist der erste Unterabschnitt des Artikels.</para>
     </sect2>
   </sect1>
 </article>

A.3. Ausgabeformate erzeugen

   Fu:r diesen Abschnitt wird vorausgesetzt, dass die im Port
   textproc/docproj enthaltene Software manuell oder u:ber das Portssystem
   installiert wurde. Weiter wird vorausgesetzt, dass alle Programme
   unterhalb des Verzeichnisses /usr/local installiert worden sind und die
   Verzeichnisse, die die ausfu:hrbaren Programme enthalten, in der Variable
   PATH enthalten sind.

  A.3.1. Benutzung von Jade

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

 % jade -V nochunks \  1
 -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ 2
 -c /usr/local/share/xml/docbook/catalog \
 -c /usr/local/share/xml/jade/catalog \
 -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \3
 -t sgml 4 datei.xml > datei.html 5

   1 U:bergibt den Parameter nochunks an die Stylesheets. Dadurch wird die    
     gesamte Ausgabe in die Standardausgabe geschrieben (bei der Benutzung    
     von Norm Walshs Stylesheets).                                            
   2 Legt die von Jade zur Verarbeitung beno:tigten drei Kataloge fest. Der   
     erste Katalog entha:lt Informationen zu den DSSSL-Stylesheets, der       
     zweite zur DocBook DTD und der dritte Jade-spezifische Informationen.    
   3 U:bergibt den vollen Pfad zum DSSSL-Stylesheet, das von Jade zur         
     Verarbeitung des Dokuments benutzt wird.                                 
   4 Weist Jade an, eine Transformation von einer DTD zu einer anderen DTD    
     vorzunehmen. In diesem Falle, von der DocBook DTD zur HTML DTD.          
   5 Legt fest, welche Datei Jade verarbeiten soll und leitet die Ausgabe in  
     die Datei datei.html um.                                                 

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

 % jade \
 -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ 1
 -c /usr/local/share/xml/docbook/catalog \
 -c /usr/local/share/xml/jade/catalog \
 -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \2
 -t sgml 3 datei.xml 4

   1 Legt die von Jade zur Verarbeitung beno:tigten drei Kataloge fest. Der   
     erste Katalog entha:lt Informationen zu den DSSSL-Stylesheets, der       
     zweite zur DocBook DTD und der dritte Jade-spezifische Informationen.    
   2 U:bergibt den vollen Pfad zum DSSSL-Stylesheet, das von Jade zur         
     Verarbeitung des Dokuments benutzt wird.                                 
   3 Weist Jade an, eine Transformation von einer DTD zu einer anderen DTD    
     vorzunehmen. In diesem Falle, von der DocBook DTD zur HTML DTD.          
   4 Legt die zu verarbeitende Datei fest. Die Stylesheets ermitteln          
     eigensta:ndig die Namen aller HTML-Ausgabedateien.                       

   Abha:ngig von der Struktur des zu verarbeitenden Dokumentes und den
   Stylesheetregeln zur Aufteilung des Dokumentes, kann dieser Befehl auch
   nur eine einzelne HTML-Datei erzeugen.

   Beispiel A.5. Ein DocBook-Dokument nach Postscript umwandeln

   Um eine Postscript-Ausgabe zu erzeugen, muss zuerst die XML-Quelle in eine
   TeX-Datei umgewandelt werden.

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

   1 Weist die Stylesheets an, verschiedene TeX-spezifische Optionen zu       
     benutzen.                                                                
   2 Legt die von Jade zur Verarbeitung beno:tigten drei Kataloge fest. Der   
     erste Katalog entha:lt Informationen zu den DSSSL-Stylesheets, der       
     zweite zur DocBook DTD und der dritte Jade-spezifische Informationen.    
   3 U:bergibt den vollen Pfad zum DSSSL-Stylesheet, das von Jade zur         
     Verarbeitung des Dokuments benutzt wird.                                 
   4 Weist Jade an, die Ausgabe in eine TeX-Datei umzuwandeln.                

   Die so erzeugte .tex-Datei muss anschliessend mittels tex, unter Angabe
   des Makropakets &jadetex weiterverarbeitet werden.

 % tex "&jadetex" datei.tex

   tex muss mindestens dreimal ausgefu:hrt werden. Der erste Lauf ermittelt
   die die Querverweise innerhalb des Dokumentes, die fu:r
   Stichwortverzeichnisse und a:hnliches beno:tigt werden.

   Warnungen, wie LaTeX Warning: Reference `136' on page 5 undefined on input
   line 728., die zu diesem Zeitpunkt ausgegeben werden, ko:nnen ohne
   weiteres ignoriert werden.

   Der zweite Lauf kann jetzt, da mehr Informationen, wie zum Beispiel die
   Seitenla:ngen, zur Verfu:gung stehen, Eintra:ge im Stichwortverzeichnis
   und Querverweise genauer bestimmen.

   Der dritte Lauf ist fu:r abschliessende Aufra:umarbeiten notwendig. Die so
   von tex erzeugte Ausgabe befindet sich anschliessend in der Datei
   datei.div.

   Zum Schluss muss noch dvips aufgerufen werden, um die .div-Datei in ein
   Postscript-Dokument umzuwandeln.

 % dvips -o datei.ps datei.dvi

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

   Die ersten Schritte, um ein DocBook-Dokument in ein PDF umzuwandeln,
   stimmen mit denen u:berein, die notwendig sind, um eine Postscript-Ausgabe
   zu erzeugen (Beispiel A.5, "Ein DocBook-Dokument nach Postscript
   umwandeln").

   Nachdem die .tex-Datei durch Jade erzeugt wurde, muss pdfTeX stattdessen
   mit dem Makropaket &pdfjadetex aufgerufen werden.

 % pdftex "&pdfjadetex" datei.tex

   Dieser Befehl muss ebenfalls dreimal ausgefu:hrt werden. Am Ende liegt mit
   datei.pdf das fertige PDF-Dokument vor. Weitere Schritte sind jetzt nicht
   mehr notwendig.

                              Stichwortverzeichnis
