From 6f1c49b780fd9fc90e2b3625c0bba64e5b06a5c5 Mon Sep 17 00:00:00 2001 From: Martin Heinen Date: Tue, 23 Dec 2003 01:04:36 +0000 Subject: [PATCH] MFbed: "Die Fibel" - The German version of the FDP Primer. Submitted by: Oliver Fischer --- de_DE.ISO8859-1/books/fdp-primer/Makefile | 51 + de_DE.ISO8859-1/books/fdp-primer/book.sgml | 345 +++ de_DE.ISO8859-1/books/fdp-primer/chapter.decl | 2 + de_DE.ISO8859-1/books/fdp-primer/chapters.ent | 27 + .../books/fdp-primer/doc-build/chapter.sgml | 54 + .../books/fdp-primer/examples/appendix.sgml | 54 + .../books/fdp-primer/overview/chapter.sgml | 348 +++ .../books/fdp-primer/psgml-mode/chapter.sgml | 206 ++ .../books/fdp-primer/see-also/chapter.sgml | 143 ++ .../books/fdp-primer/sgml-markup/chapter.sgml | 55 + .../books/fdp-primer/sgml-primer/chapter.sgml | 1984 +++++++++++++++++ .../books/fdp-primer/structure/chapter.sgml | 54 + .../books/fdp-primer/stylesheets/chapter.sgml | 53 + .../books/fdp-primer/the-website/chapter.sgml | 53 + .../books/fdp-primer/tools/chapter.sgml | 363 +++ .../fdp-primer/translations/chapter.sgml | 53 + .../fdp-primer/writing-style/chapter.sgml | 54 + 17 files changed, 3899 insertions(+) create mode 100644 de_DE.ISO8859-1/books/fdp-primer/Makefile create mode 100644 de_DE.ISO8859-1/books/fdp-primer/book.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/chapter.decl create mode 100644 de_DE.ISO8859-1/books/fdp-primer/chapters.ent create mode 100644 de_DE.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/examples/appendix.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/overview/chapter.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/see-also/chapter.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/structure/chapter.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/the-website/chapter.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/tools/chapter.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/translations/chapter.sgml create mode 100644 de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml diff --git a/de_DE.ISO8859-1/books/fdp-primer/Makefile b/de_DE.ISO8859-1/books/fdp-primer/Makefile new file mode 100644 index 0000000000..593fae312c --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/Makefile @@ -0,0 +1,51 @@ +# +# $FreeBSD$ +# $FreeBSDde: de-docproj/books/fdp-primer/Makefile,v 1.2 2003/11/26 01:11:56 mheinen Exp $ +# basiert auf: 1.12 +# +# Build the FreeBSD Documentation Project Primer. +# +MAINTAINER=nik@FreeBSD.org + +DOC?= book + +FORMATS?= html-split html + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS= book.sgml +SRCS+= overview/chapter.sgml +SRCS+= psgml-mode/chapter.sgml +SRCS+= see-also/chapter.sgml +SRCS+= sgml-markup/chapter.sgml +SRCS+= sgml-primer/chapter.sgml +SRCS+= stylesheets/chapter.sgml +SRCS+= structure/chapter.sgml +SRCS+= doc-build/chapter.sgml +SRCS+= the-website/chapter.sgml +SRCS+= tools/chapter.sgml +SRCS+= translations/chapter.sgml +SRCS+= writing-style/chapter.sgml + +SRCS+= examples/appendix.sgml + +# 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 + +# Entities +SRCS+= chapters.ent + +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/de_DE.ISO8859-1/books/fdp-primer/book.sgml b/de_DE.ISO8859-1/books/fdp-primer/book.sgml new file mode 100644 index 0000000000..a42e73ab0b --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/book.sgml @@ -0,0 +1,345 @@ + + + +%authors; + + +%translators; + + +%mailing-lists; + + +%man; + + +%chapters; + + + +]> + + + + Die Fibel für neue Mitarbeiter des + FreeBSD-Dokumentationsprojekts + + + Nik + Clayton + +
nik@FreeBSD.org
+ + + + + 1998 + 1999 + 2000 + 2001 + 2002 + 2003 + Nik Clayton + + + $FreeBSD$ + + $FreeBSD$ + + + 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: + + + + 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. + + + + Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must + reproduce the above copyright notice, this list of conditions and + the following disclaimer in the documentation and/or other + materials provided with the distribution. + + + + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR + ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH + DAMAGE. + + + + + Vielen Dank für Ihr Interesse und Ihre Mitarbeit an + der FreeBSD-Dokumentation. Jeder Beitrag ist für uns sehr + wichtig. + + In dieser Fibel wird von der eingesetzten Software bis hin + zu den Vorstellungen des FreeBSD-Dokumentationsprojekts alles + behandelt, was Sie wissen müssen, wenn Sie sich am + FreeBSD-Dokumentationsprojekt beteiligen wollen. + + Bitte beachten Sie, daß diese Fibel + ständig unter Bearbeitung und noch + nicht vollständig ist. Die noch nicht abgeschlossenen + Kapitel sind mit einem * vor der + Kapitelüberschrift gekennzeichnet. + + + Die noch nicht übersetzten Kapitel sind zusätzlich mit + einen # gekennzeichnet. + + + + + Benutzungshinweise + + + Die Eingabeaufforderungen + + Die folgende Tabelle zeigt die normale Eingabeaufforderung + des Systems und die Eingabeaufforderung des Superusers. Die in + diesem Buch vorkommenden Beispiele, benutzen die jeweilige + Eingabeaufforderung um zu zeigen, unter welchem Benutzer die + Beispiele ausgeführt werden sollten. + + + + + + Benutzer + Eingabeaufforderung + + + + + + Normaler Benutzer + &prompt.user; + + + + Superuser + &prompt.root; + + + + + + + + Typographische Festlegungen + + Um die Lesbarkeit zu erhöhen, werden in diesem + Dokument die im folgenden genannten typographischen + Festlegungen verwendet: + + + + + + Bedeutung + Beispiel + + + + + + Kommandonamen, Dateien, Verzeichnisse sowie + Bildschirmausgaben. + Bearbeiten Sie die Datei + .loginFühren + Sie ls -a aus, um sich alle + Dateien anzeigen zulassen.Sie haben Post. + + + + Eingaben und die dazugehörige + Computerausgabe. + &prompt.user; su +Paßwort: + + + + Referenzen auf Hilfeseiten. + + Mit + su + 1 + können Sie sich als anderer + Benutzer anmelden. + + + + Benutzer- und Gruppennamen. + + Ich bin root, ich darf + das. + + + + Hervorhebungen + + Hier müssen Sie + vorsichtig sein. + + + + Argumente auf der Kommandozeile, die durch + existierende Namen, Dateien oder Variablen ersetzt + werden müssen. + + Dateien können Sie mit dem Befehl + rm + Dateiname + löschen. + + + + Umgebungsvariablen + + $HOME ist Ihr + Benutzerverzeichnis. + + + + + + + + Anmerkungen, Tips, wichtige Hinweise, Warnungen und + Beispiel + + An einigen Stellen innerhalb dieses Buchs werden + wichtige oder nützliche Hinweise gegeben, die besonders + hervorgehoben sind. Hier ein kurzer Überblick über + die verwendeten Darstellungen. + + + + Anmerkungen werden so dargestellt. Sie enthalten + Informationen die Sie nur zu lesen brauchen, wenn Sie direkt + davon betroffen sind. + + + + Tipps sind Informationen, die vielleicht hilfreich sein + könnten oder aufzeigen, wie bestimmte Dinge einfacher + zu bewerkstelligen sind. + + + + Besonders wichtige Punkte werden so hervorgehoben. Meist + enthalten sie Hinweise auf vielleicht zusätzlich auszuführende + Schritte oder Dinge, die besonders zu beachten sind. + + + + Warnungen werden wie dieser Abschnitt dargestellt und + weisen auf mögliche Schäden hin, die entstehen + können, falls die beschriebenen Schritte nicht genau + befolgt oder Hinweise nicht beachtet werden. Die Palette der + möglichen Schäden reicht von Hardwareschäden + bis hin zu Datendatenverlust durch ein versehentliches + Löschen von wichtigen Dateien oder ganzen + Verzeichnissen. + + + + Ein Beispiel + + Beispiele, die so wie hier dargestellt werden, enthalten + meist kleine Übungen, die nachvollzogen werden sollten, + um das vorher beschriebene besser zu verinnerlichen oder mit + den erzeugten Ausgaben vertraut zu werden. + + + + + Danksagungen + + Ich möchte mich bei Sue Blake, Patrick Durusau, Jon + Hamilton, Peter Flynn und Christopher Maden bedanken, die sich + die Zeit genommen haben, die frühen Entwürfe dieses + Dokuments zu lesen und viele hilfreiche Hinweise und + Ratschläge gegeben haben. + + + + &chap.overview; + &chap.tools; + &chap.sgml-primer; + &chap.sgml-markup; + &chap.stylesheets; + &chap.structure; + &chap.doc-build; + &chap.the-website; + &chap.translations; + &chap.writing-style; + &chap.psgml-mode; + &chap.see-also; + + &app.examples; + + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/chapter.decl b/de_DE.ISO8859-1/books/fdp-primer/chapter.decl new file mode 100644 index 0000000000..3e187a32ee --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/chapter.decl @@ -0,0 +1,2 @@ + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/chapters.ent b/de_DE.ISO8859-1/books/fdp-primer/chapters.ent new file mode 100644 index 0000000000..431bb633f3 --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/chapters.ent @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml new file mode 100644 index 0000000000..2e73804628 --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml @@ -0,0 +1,54 @@ + + + + # Die Erzeugung der Zieldokumente + + Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie + bitte + das Original in englischer Sprache. + + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/examples/appendix.sgml b/de_DE.ISO8859-1/books/fdp-primer/examples/appendix.sgml new file mode 100644 index 0000000000..3e24275d58 --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/examples/appendix.sgml @@ -0,0 +1,54 @@ + + + + # Beispiele + + Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie + bitte + das Original in englischer Sprache. + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/overview/chapter.sgml new file mode 100644 index 0000000000..ee14403824 --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/overview/chapter.sgml @@ -0,0 +1,348 @@ + + + + Überblick + + Herzlich Willkommen beim FreeBSD-Dokumentationsprojekt. + Qualitativ hochwertige Dokumentation ist ein wichtiger + Erfolgsfaktor und sehr bedeutend für die Verbreitung von + FreeBSD. Die wichtigste Quelle dafür ist das + FreeBSD-Dokumentationsprojekt (FDP). Jeder Beitrag, der zu diesem + Projekt geleistet wird, ist ungemein wertvoll. + + Es ist das Anliegen dieser Fibel, den Leser mit dem FDP + vertraut zu machen und zu erklären, wie das FDP + organisiert ist, wie man selber Dokumente + erstellt und an das FDP einreicht und wie + die verfügbaren Werkzeuge effektiv beim Schreiben + eingesetzt werden können. + + Wie jedes Opensourceprojekt, ist auch das FDP auf die Mithilfe + vieler angewiesen. Deshalb ist jeder herzlich eingeladen + mitzuarbeiten. Die dafür erforderlichen Voraussetzungen sind + gering und es gibt keine Verpflichtung eine bestimmte Menge an + Dokumenten pro Monat oder Jahr beizusteuern. Das Einzige was Sie + tun müssen, ist sich auf der Mailingliste &a.doc; einzutragen. + + Nach dem Lesen der FDP-Fibel sollte man wissen: + + + + welche Dokumente durch das FDP betreut werden, + + + + wie man SGML-Dokumente liest und den SGML-Quellcode der + durch das FDP betreuten Dokumente versteht, + + + + wie man selbst Änderungen an Dokumenten vornehmen + kann und + + + + wie man Änderungen zur Begutachtung durch das FDP + einreichen kann. + + + + + Die FreeBSD-Dokumentationsreihe + + Das FDP umfaßt vier verschiedene Kategorien: + + + + Hilfeseiten + + + Die englischen Hilfeseiten wurden nicht vom FDP + geschrieben, da sie ein Teil des Basissystems sind. Jedoch + können bzw. wurden bereits Teile von existierenden + Hilfeseiten umformuliert, um sie verständlicher zu + machen oder um Fehler zu beheben. + + Für die Übersetzung der Hilfeseiten des + Systems in die verschiedenen Sprachen sind die einzelnen + Übersetzergruppen verantwortlich. Alle dabei + entstandenen Übersetzungen gehören zum + FDP. + + + + + Die FAQ + + + Das Ziel der FAQ ist es, Fragen, die auf den + verschiedenen Maillinglisten und in Newsgruppen + regelmäßig diskutiert werden, nach einem + einfachen Frage- und Antwort-Muster zu behandeln. Das + schließt nicht aus, das auf bestimmte Fragen + ausführlich und umfassend eingegangen wird. + + + + + Das Handbuch + + + Das Ziel des Handbuches ist es, die + umfassende Quelle und Referenz im Netz für + FreeBSD-Benutzer zu sein. + + + + + Die Webseite + + + Die Webseite http://www.FreeBSD.org + und ihre vielen Spiegel auf der ganzen Welt vertreten das + FreeBSD-Projekt im WWW. Für viele Menschen + ist sie der erste Kontakt mit FreeBSD. + + + + + Jede dieser vier Kategorien wird im FreeBSD-CVS-Baum + verwaltet. Das bedeutet, daß alle Änderungen an den + Dateien für jeden verfügbar sind und jeder sich + mittels eines Programms wie CVSup + oder CTM eine lokale Kopie der + Dokumentation anlegen kann. + + Parallel zum FDP haben viele Menschen Anleitungen + geschrieben und Webseiten mit Bezug zu FreeBSD erstellt. Einige + davon werden im CVS-Archiv verwaltet, sofern der Autor dem + zugestimmt hat. In anderen Fällen hat sich der Autor + entschlossen, seine Dokumentation außerhalb des zentralen + FreeBSD-CVS-Archivs zu verwalten. Das FDP bemüht sich, so + viele Verweise wie möglich auf solche Quellen + bereitzustellen. + + + + Bevor es losgeht + + Zum Verständnis der folgenden Kapitel sollte folgendes + bereits bekannt sein: + + + + Wie eine aktuelle Kopie der FreeBSD-Dokumentation + entweder auf Basis des FreeBSD-CVS-Archivs mittels + CVS, + CTM oder + CVSup angelegt und gepflegt wird, + oder wie mit CVSup eine frische + Kopie des CVS-Archivs heruntergeladen wird. + + + + Wie neue Programme mit Hilfe des + FreeBSD-Portsystems oder mittels &man.pkg.add.1; + heruntergeladen und installiert werden. + + + + + + Der Schnellstart + + Falls man einfach loslegen möchte und sich sicher genug + fühlt, um alles weitere erst bei Bedarf nachzusehen, kann + man einfach den folgenden Anweisungen folgen: + + + + Zuerst muß der Metaport textproc/docproj auf dem + betreffenden Arbeitsrechner installiert werden. + + &prompt.root; cd /usr/ports/textproc/docproj +&prompt.root; make JADETEX=no install + + + + Anschließend sollte eine lokale Kopie des + FreeBSD-doc-Verzeichnisbaumes angelegt + werden. Hierfür kann man entweder auf + CVSup im + checkout-Modus zurückgreifen oder + mittels cvs eine komplette Kopie + des CVS-Archivs anlegen. + + Wenn man lieber mit einer Kopie des CVS-Archivs arbeiten + möchte, werden als Minimum die Verzeichnisse + doc/share und + doc/de_DE.ISO8859-1/share + benötigt. + + &prompt.user; cvs checkout doc/share +&prompt.user; cvs checkout doc/de_DE.ISO8859-1/share + + Für den Fall, daß ausreichend Platz auf der + Festplatte vorhanden ist, kann auch eine eine + vollständige Arbeitskopie des gesamten CVS-Baumes anlegt + werden. + + &prompt.user; cvs checkout doc + + + + Sollte geplant sein, ein existierendes Buch oder einen + existierenden Artikel zu ändern, muß + natürlich noch zusätzlich das betreffende + Verzeichnis aus dem CVS-Archiv geholt werden. Soll hingegen + ein neues Buch oder ein neuer Artikel geschrieben werden, + empfiehlt es sich, auf bestehende Bücher und Artikel + zurückzugreifen und diese als Vorlage zu nutzen. + + Ein Artikel über die Konfiguration eines VPNs + zwischen FreeBSD und Windows 2000 kann wie + folgt erstellt werden: + + + + Zuerst wird das Verzeichnis + articles aus dem FreeBSD-CVS-Archiv + lokal angelegt: + + &prompt.user; cvs checkout doc/de_DE.ISO8859-1/articles + + + + Anschließend kopiert man einen bereits + existierenden Artikel und nutzt ihn als Vorlage. In + diesem Beispiel soll der neue Artikel im Verzeichnis + vpn-w2k liegen: + + &prompt.user; cd doc/de_DE.ISO8859-1/articles +&prompt.user; cp -r committers-guide vpn-w2k + + + + Bereits exisitierende Dokumente, die geändert + werden sollen, können direkt aus dem CVS-Archiv + geholt werden. Das folgende Beispiel zeigt das + für die FAQ aus dem Verzeichnis + doc/de_DE.ISO8859-1/books/faq: + + &prompt.user; cvs checkout doc/de_DE.ISO8859-1/books/faq + + + + Jetzt können die .sgml Dateien + mit einem beliebigen Texteditor bearbeitet werden. + + + + + Danach ist make mit dem Ziel + lint aufzurufen, um das gesamte + Dokument auf Auszeichnungsfehler hin zu untersuchen, ohne + das zeitaufwendige Transformationen vorgenommen + werden. + + &prompt.user; make lint + + + + Soll anschließend das Zieldokument erstellt + werden, kann mit Hilfe der Variable + FORMATS bestimmt werden, welche + Ausgabeformate erzeugt werden sollen. Unterstützt werden + momentan html, + html-split, txt, + ps, pdf und + rtf. Die aktuelle Liste der + unterstützten Formate befindet sich am Anfang der Datei + doc/share/mk/doc.docbook.mk. Bei der + Verwendung dieser Variable ist es wichtig, darauf zu achten, + daß die Angabe der gewünschten Formate in + Anführungszeichen eingeschlossen wird, sofern mehr als + nur ein Format gleichzeitig erstellt werden soll. + + Wenn das Dokument beispielsweise nach + HTML konvertiert werden soll, kann dies + so vorgenommen werden: + + &prompt.user; make FORMATS=html + + Soll es hingegen in den Formaten html + und txt erzeugt werden, + kann man entweder + &man.make.1; zweimal hintereinander aufrufen: + + &prompt.user; make FORMATS=html +&prompt.user; make FORMATS=txt + + oder beide Formate mit einem Aufruf von &man.make.1; + erzeugen: + + &prompt.user; make FORMATS="html txt" + + + + Zum Schluß müssen die Änderungen an das + FDP mittels &man.send-pr.1; eingesandt werden. + + + + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml new file mode 100644 index 0000000000..87fa59330e --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml @@ -0,0 +1,206 @@ + + + + <literal>sgml-mode</literal> und + <application>Emacs</application> + + Neuere Emacs- und + XEmacs-Versionen verfügen + über ein nützliches Lisp-Paket namens PSGML. PSGML ist + ein sogenannter Majormode, der + Funktionen speziell für den Umgang mit SGML-Dateien, + -Elementen und deren Attributen bereit stellt. Emacs aktiviert + PSGML automatisch, wenn eine Datei mit der Endung + .sgml geladen oder der Befehl M-X + sgml-mode eingegeben wird. + + Die Arbeit an SGML-Dokumenten wie dem FreeBSD-Handbuch kann + sich wesentlich einfacher gestalten, wenn einige der Funktionen + von PSGML gekannt sind: + + + + C-c C-e + + + Ruft die Funktion sgml-insert-element + auf, die nach dem Namen des einzufügenden Elements + fragt. Ist dieser eingegeben worden und wurde die + Eingabetaste gedrückt, fügt die + Funktion Start- und Endtag des neuen Elements ein. Sofern + das eingefügte Element laut DTD andere Elemente + enthalten muß, werden diese ebenfalls + miteingefügt. + + + Falls man unsicher ist, wie der Name des + gewünschten Elements lautet oder welche Elemente an der + aktuellen Position erlaubt sind, können mittels der + Taste Tab alle an dieser + Stelle möglichen Elemente angezeigt + werden. Ebenso ermöglicht Tab die + Vervollständigung eines bereits eingegebenen + Elementnamens. + + + + + + + C-c = + + + Ruft die Funktion + sgml-change-element-name auf, mit der das + aktuelle Element – das Element zwischen dessen Start- + und Endtag sich der Cursor befindet – ausgewechselt + werden kann. Die Funktion fragt nach dem Namen des neuen + Elements und ersetzt anschließend Start- und Endtag + des alten Elements durch die des neuen Elements. + + + + + C-c C-r + + + Ruft die Funktion sgml-tag-region + auf, die einen markierten Textabschnitt mit einem Element + umschließt. Dazu wird zuerst nach dem Namen des + einzufügenden Elements gefragt, und dann dessen + Starttag am Anfang und dessen Endtag am Ende des markierten + Textes einfügt. + + + + + C-c - + + + Ruft die Funktion sgml-untag-element + auf, die Start- und Endtag des Elements entfernt, innerhalb + dessen sich der Cursor befindet. + + + + + C-c C-q + + + Ruft die Funktion sgml-fill-element + auf. Diese Funktion formatiert + Formatieren bedeutet in diesem Zusammenhang, + daß die Funktion versucht, soviel Zeichen wie + möglich in einer Zeile unterzubringen. Die Stelle, + bis zu der gefüllt und dann der Zeilemumbruch + erfolgt, ist konfigurierbar. + den Inhalt des aktuellen Elements neu. Dieser + Vorgang betrifft auch Elemente wie + programlisting, in denen Leerzeichen und + ähnliches Teil der Formatierung sind. Aus diesem Grund + ist mit sgml-fill-element bedächtig + umzugehen. + + + + + C-c C-a + + + Ruft die Funktion + sgml-edit-attributes auf. Diese + öffnet einen zweiten Puffer mit allen Attributen des + Elements, innerhalb dessen sich der Cursor befindet. + Über Tab kann von einem Attribut zum + nächsten gewechselt werden. Ein existierender + Attributwert kann mit C-k gelöscht + werden. Die Tastenfolge C-c C-c + schließt den Puffer und setzt die Attribute des + Elements entsprechend den Puffervorgaben. + + + + + C-c C-v + + + Ruft die Funktion sgml-validate auf, + die zuerst fragt, ob das aktuelle Dokument gespeichert + werden soll und anschließend einen SGML-Validator + aufruft. Die Ausgaben des Validators werden in einem neuen + Puffer angezeigt. Dadurch hat der Benutzer die + Möglichkeit, eventuell vom Validator gefundene Fehler + zu korrigieren. + + + + + Zweifellos hat PSGML noch weitere nützliche Funktionen, doch + die hier genannten sind die, die der Autor dieser Fibel am meisten + benutzt. + + Um den richtigen Einzug, die Umwandlung von Tabulatoren in + Leerzeichen und die maximale Zeilenlänge für Dokumente des FDPs + sicherzustellen, kann folgender Eintrag in + .emacs vorgenommen werden: + + (setq sgml-mode-hook + '(lambda () + (setq fill-column 70 + indent-tabs-mode nil + next-line-add-newlines nil + standard-indent 2) + (auto-fill-mode t))) + + + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/see-also/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/see-also/chapter.sgml new file mode 100644 index 0000000000..172086ad62 --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/see-also/chapter.sgml @@ -0,0 +1,143 @@ + + + + Weiterführende Quellen + + In dieser Fibel werden absichtlich nicht alle Aspekte von + SGML, der erwähnten DTDs und des + FreeBSD-Dokumentationsprojekts behandelt. Interessierten werden daher + die nachfolgenden Quellen empfohlen. + + + Das FreeBSD-Dokumentationsprojekt + + + + Die + Webseiten des + FreeBSD-Dokumentationsprojektes + + + + Das + FreeBSD-Handbuch + + + + + + SGML + + + + Die + SGML/XML-Webseite, eine umfangreiche Quelle zu + SGML. + + + + Gentle + introduction to SGML + + + + + + HTML + + + + Das + World-Wide-Web-Konsortium + + + + Die + HTML 4.0-Spezifikation + + + + + + 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 für DocBook-Benutzer an. + + + + + + Das Linux-Dokumentationsprojekt + + + + Die Webseiten des Linux-Dokumenationsprojektes. + + + + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml new file mode 100644 index 0000000000..f4936d6d0c --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -0,0 +1,55 @@ + + + + # Auszeichnung mit SGML + + Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie + bitte + das Original in englischer Sprache. + + + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml new file mode 100644 index 0000000000..7c70a68bd7 --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -0,0 +1,1984 @@ + + + + + + Die SGML-Fibel + + Die Mehrzahl der Dokumente des FDPs sind in SGML geschrieben. + Ziel dieses Kapitels ist es, genau zu erklären, was + das bedeutet und wie man die SGML-Quellen liest und versteht. + Ebenso werden die in den Quellen genutzten Kniffe erklärt, + auf die man beim Lesen der Dokumente stoßen wird. + + Teile dieses Kapitels basieren auf Mark Galassis Get + Going With DocBook. + + + Überblick + + In den guten alten Zeiten war der Umgang mit + elektronischem Text einfach. Man mußte + 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. + + + + Unleugbar ist, daß das nicht genug war. Von einem + machinenlesbaren Text wird erwartet, daß er auch von + Maschinen gelesen und vernünftig verarbeitet werden kann. + Einige Stellen sollen hervorgehoben werden, andere sollen in ein + Glossar aufgenommen werden oder auf andere Textstellen + verweisen. Dateinamen wiederum sollen in einer + schreibmaschinenähnlichen Schrift auf dem + Bildschirm dargestellt werden, der Ausdruck jedoch soll in + Schrägschrift oder einer von hundert anderen + möglichen Darstellungsformen erfolgen. + + + + Anfänglich gab es die Hoffnung, daß die + Künstliche Intelligenz (KI) helfen würde, dieses Ziel + zu erreichen. Der Computer sollte den Text lesen und + selbstständig in der Lage sein können, wichtige + Formulierungen, Dateinamen, Benutzereingaben oder Beispiele zu + erkennen. Unglücklicherweise verlief die Entwicklung in der + Wirklichkeit nicht wie gewünscht und Computer bedürfen + etwas Unterstützung, bevor sie Texte vernünftig + verarbeiten können. + + Genauer gesagt, man muß ihnen sagen, was was ist. Sehen + wir Menschen uns folgende Zeilen an: + +
+ Löschen Sie /tmp/foo mittels &man.rm.1;. + + &prompt.user; rm /tmp/foo +
+ + fällt es 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 Im + angelsächischschen Sprachraum wird von + markup + gesprochen. bedeutet, daß + sich der Wert eines Textes erhöht, aber auch seine Kosten. + Durch Auszeichnungen wird einem Dokument zusätzlicher Text + hinzugefügt, der aber von dem eigentlichen Dokumenteninhalt + auf eine bestimmte Art und Weise unterschieden werden kann, so + daß Programme die Auszeichnung erkennen können und + mittels dieser Informationen während der Verarbeitung in + der Lage sind, Entscheidungen zu treffen. Texteditoren + können diese Auszeichnungselemente vor dem Benutzer + verbergen, um zu vermeiden, daß er durch sie abgelenkt + wird. + + + + + Die durch die Auszeichnungselemente im Textdokument + zusätzlich abgelegten Informationen erhöhen den Wert + des Dokuments. Allerdings muß diese Arbeit in den meisten + Fällen von einem Menschen getan werden – wären + Maschinen dazu fähig, wären zusätzliche + Auszeichnungselemente unnötig. Der damit verbundene Aufwand + erhöht die Kosten, die durch die + Erstellung des Dokuments entstehen. + + Das etwas weiter oben gegebene Beispiel sieht im Quelltext + so aus: + + Löschen Sie /tmp/foo mittels &man.rm.1;. + +&prompt.user; rm /tmp/foo]]> + + Die Auszeichnungselemente sind deutlich vom eigentlichen + Inhalt zu unterscheiden. + + Leicht ist zu erkennen, daß die Einführung von + Auszeichnungselementen es nötig macht, irgendwo festzulegen + was die einzelnen Auszeichungselemente bedeuten und wie sie zu + interpretieren sind. Letztendlich wird ein ganzes Bündel + von Auszeichnungselementen benötigt, die selbst eine eigene + Auszeichnungssprache darstellen, derer man sich bedienen kann, + wenn man seine Dokumente schreibt. + + Natürlich kann es keine universelle + Auszeichnungssprache geben und eine einzige mag nicht + ausreichend für alle möglichen Anwendungsfälle + sein. Eine Sprache für technische Dokumente wird sich + wahrscheinlich stark von einer für Kochrezepte + unterscheiden. Die universelle Lösung ist eine + Basissprache, mit deren Hilfe weitere Sprachen entwickelt werden + können – eine + Meta-Auszeichungssprache also. + + Genau diese Anforderung wird von der Standard Generalized + Markup Language (SGML) erfüllt. Mit ihrer + Hilfe wurden viele andere Auszeichungssprachen wie + beispielsweise HTML und DocBook, welche beide von FDP genutzt + werden, entwickelt. + + Die eigentliche Sprachdefinition erfolgt in einer + Dokumenten-Typ-Definition (DTD). Innerhalb dieser DTD werden die + Namen der einzelnen Elemente, deren mögliche Reihenfolge + und Verschachtelung sowie weitere Informationen + festgelegt. + + + + + + Eine DTD ist eine + vollständige Definition aller + möglichen Sprachelemente, ihrer + ReihenfolgeBei natürlichen Sprachen spricht + man vom Satzbau – demjenigen Konstrukt, das unter + anderem die Position des Subjekts, Objekts und + Prädikats in einem Satz festlegt., + optionaler Elemente und so weiter und so weiter. Dank dieser + recht formalen Festlegung ist es möglich, + SGML-Parser zu entwickeln, die sowohl ein + Dokument als auch seine DTD einlesen und anhand dieser DTD + prüfen können, ob das Dokument allen Anforderungen der + DTD entspricht. Dieser Vorgang wird allgemein als + Validierung des Dokuments + bezeichnet. + + + Das Validieren eines SGML-Dokuments gegen eine DTD + überprüft lediglich die korrekte Syntax des + Dokuments, daß heißt, ob nur gültige + Auszeichnungselemente verwendet wurden und ihre Reihenfolge + stimmt. Dabei wird nicht geprüft, ob + die Elemente der DTD sinngemäß + verwandt wurden. Sollten beispielsweise alle Dateinamen als + Funktionsnamen ausgezeichnet worden sein, so würde der + Parser keinen Fehler signalisieren. Formaler ausgedrückt: + Der Parser prüft die Syntax, aber nicht die + Semantik. + + + Es ist anzunehmen, daß, wenn man selber vor hat + Dokumentation für das FDP zu schreiben, der + größte Teil davon mit Hilfe von HTML oder DocBook + geschrieben werden wird. Aus diesem Grunde wird an dieser Stelle + nicht erklärt, wie eine DTD entwickelt wird. + + + + 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, unabhängig, ob es sich um eine + einzelne Webseite oder ein langes Buch handelt, wird angenommen, + daß es einen wie auch immer gearteten Inhalt hat. Dieser + läßt 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 enthält nun + sicherlich Kapitel, die selbst zu Recht als Elemente bezeichnet + werden können. Jedes einzelne Kapitel enthält weitere + Elemente. So gibt es beispielsweise Absätze, Zitate und + Fußnoten. 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 möchte, kann man sich das als + UnterteilungIm + angelsächsichen Sprachraum wird hier von + chunking gesprochen. 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 Absätze, Fußnoten, Namen und so weiter + und so weiter. + + Anzumerken ist an dieser Stelle, daß das eben gesagte + ohne weiteres auf jeden Inhaltstyp angewandt werden kann, auch + ohne daß von SGML die Rede ist. Man + kö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 muß ein anderer Weg gewählt werden, um zu + bestimmen, zu welchem Element die einzelnen Inhalte + gehören. In SGML-basierten Auszeichnungssprachen wie HTML + und DocBook werden dafür sogenannte + Tags eingesetzt. + + Mit einem solchen Tag wird eindeutig festgelegt, wo ein + bestimmtes Element beginnt und wo es endet. Allerdings + gehö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 + natürlich auch unterschiedlich benannt sein werden. + + Der Starttag für ein imaginäres Element mit dem + Namen elementname ist + <elementname>. + Sein Gegenstück, der schließende Endtag, ist + </elementname>. + + + Verwendung eines Elements (Start- und Endtag) + + HTML kennt das Element p, um + festzulegen, daß ein bestimmter abgegrenzter Bereich + einen Absatz darstellt. Dieses Element hat sowohl einen Start- + als auch einen Endtag. + + Das ist ein Absatz. Er beginnt mit Starttag + für das Element 'p' und endet mit dem Endtag für + das Element 'p'.

+ +

Das ist ein etwas kürzerer Absatz.

]]> + + + + Elemente müssen nicht notwendigerweise einen Endtag + haben. Ebenso ist es nicht notwendig, daß Elemente einen + Inhalt haben. Beispielsweise kann in HTML-Dokumenten mittels + eines speziellen Elements festgelegt werden, daß eine + horizontale Linie an einer bestimmten Stelle erscheinen soll. Da + dieses Element offensichtlich keinen Inhalt hat, wird auch kein + Endtag benötigt. + + + Verwendung eines Elements (nur Starttag) + + In HTML kann man mit dem Element hr + festlegen, daß an einer bestimmten Stelle eine + horizontale Linie angezeigt werden soll. Da dieses Element + keinen Inhalt umschließt, hat es nur einen + Starttag. + + Das ist ein Abschnitt.

+ +
+ +

Das ist ein weiterer Absatz. Eine horizontale Linie + trennt ihn vom vorherigen Absatz.

]]> + + + Elemente können andere Elemente enthalten. Im + anfangs erwähnten Buch enthielt das Buch-Element + alle Kapitel-Elemente, die wiederum alle Absatz-Elemente + enthielten und so fort. + + + Verschachtelte Elemente: <sgmltag>em</sgmltag> + + Das ist ein einfacher Abschnitt, in dem + einige Worte hervorgehoben wurden.]]> + + + Welche Elemente andere Elemente enthalten können und + welche das sind, wird innerhalb der DTD eines Dokuments + festgelegt. + + + + + 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 wä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 von dem 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 vergegenwärtigen. + + + Elemente können selber Attribute haben, die aus einem + Namen und einem Wert bestehen. Die Attribute haben die Aufgabe, + dem Element zusätzliche Informationen hinzuzufügen. + Denkbar sind hier Festlegungen über die Darstellung, + Bezeichner, über die das Element eindeutig identifiziert + werden kann, oder beliebige andere Informationen. + + Elementattribute werden in den Starttag + eingefü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. + + + Elemente mit Attributen nutzen + + Die Verwendung des align-Attributs + für diesen Absatz ist überflüssig, da left + der Standardwert ist.

+ +

Dieser Absatz wird hoffentlich mittig dargestellt.

]]> + + + + Einige Attribute akzeptieren nur bestimmte Werte, wie + beispielsweise left oder + justify. Andere akzeptieren jeden beliebigen + Wert. Enthält der Wert des Attributs Anführungszeichen + ("), sollte er in einfachen + Anführungszeichen angegeben werden. + + + Attribute mit einfachen Anführungszeichen + + Ich stehe rechts!

]]> + + + + + + + Die Informationen ü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 müssen + von allen Programmen gefunden werden können. + + + Was dafür getan werden muß… + + Damit die Beispiele dieser Fibel ausgeführt werden + können, ist es notwendig, daß einige Programme auf + dem Rechner installiert sind und das eine Umgebungsvariable + korrekt gesetzt wird. + + + + Der erste Schritt ist die Installation des Ports + textproc/docproj + über das FreeBSD-Portsystem. textproc/docproj ist ein + Metaport, der alle vom FDP + benötigten Programme und Daten aus dem Netz laden und + installieren sollte. + + + + Anschließend muß in den Shellkonfigurationsdateien die + Variable SGML_CATALOG_FILES + Sofern man nicht an der deutschen + Dokumentation arbeitet, müssen die + Verzeichnisangaben entsprechend anpaßt + werden. + gesetzt werden. + + + <filename>.profile</filename>, für &man.sh.1; und + &man.bash.1; Benutzer + + SGML_ROOT=/usr/local/share/sgml +SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog +SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=/usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=/usr/doc/de_DE.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES +export SGML_CATALOG_FILES + + + + + <filename>.cshrc</filename>, für &man.csh.1;- und + &man.tcsh.1;-Benutzer + + setenv SGML_ROOT /usr/local/share/sgml +setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog +setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES /usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES /usr/doc/de_DE.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES + + + Damit die Änderungen wirksam werden, muß + man sich abmelden und anschließend wieder anmelden + – oder die obigen Anweisungen direkt in der Shell + ausführen und so die Umgebungsvariable + setzten. + + + + + + + Nun sollte man eine Datei + beispiel.sgml anlegen, die den + folgenden Text enthält: + + + + + + Eine Beispieldatei in HTML + + + +

Das ist ein Absatz mit etwas Text.

+ +

Das ist ein Absatz mit anderem Text.

+ +

Dieser Absatz wird rechtsbündig + ausgerichtet.

+ +]]> + + + + Nachdem die Datei abgespeichert wurde, kann sie + mit Hilfe eines SGML-Parsers validiert werden. + + Bestandteil von textproc/docproj + ist &man.nsgmls.1; - ein validierender Parser. + &man.nsgmls.1; liest ein Dokument entsprechend einer SGML-DTD + ein und gibt anschließend ein Element-Structure-Information-Set + (ESIS) aus. Allerdings ist das an dieser Stelle nicht weiter + wichtig. + + Wird &man.nsgmls.1; mit der Option + aufgerufen, werden nur Fehlermeldungen ausgegeben. Dadurch + kann leicht geprüft werden, ob ein Dokument gültig + ist oder nicht. + + So prüft man mit &man.nsgmls.1;, ob die neuangelegte + Beispieldatei gültig ist: + + &prompt.user; nsgmls -s beispiel.sgml + + Sofern das Beispiel korrekt abgetippt wurde, wird sich + &man.nsgmls.1; ohne jegliche Ausgabe beenden. Das bedeutet, + daß das Dokument erfolgreich validiert werden konnte + und somit gültig ist. + + + + Jetzt sollten die Tags title und + /title aus dem Dokument gelöscht + und das Dokument erneut validiert werden: + + &prompt.user; nsgmls -s beispiel.sgml +nsgmls:beispiel.sgml:5:4:E: character data is not allowed here +nsgmls:beispiel.sgml:6:8:E: end tag for "HEAD" which is not finished + + Die Fehlermeldungen die von &man.nsgmls.1; ausgegeben + werden, sind in durch Doppelpunkte getrennte Spalten + unterteilt. + + + + + + Spalte + Bedeutung + + + + + + 1 + Der Name des Programms, das den Fehler + meldet. Hier wird immer nsgmls + stehen. + + + + 2 + Der Name der fehlerhaften Datei. + + + + 3 + Die Zeilennummer des Fehlers. + + + + 4 + Die Spaltenummer des Fehlers. + + + + 5 + Ein einbuchstabiger Code, der über die + Art des Fehlers informiert. I + steht für eine informelle Meldung, + W für eine Warnung und + E für Fehler + Nicht immer besteht eine Meldung aus + fünf Spalten. Die Ausgabe von + nsgmls -sv ist + beispielsweise nsgmls:I: SP version + "1.3" (natürlich + abhängig von der Version). Wie man sehen + kann, handelt es sich hier um eine informelle + Meldung. + und X für + einen Querverweis. Bei den oben stehenden Ausgaben + handelt es sich also um Fehlermeldungen. + + + + 6 + Die Fehlermeldung. + + + + + + Durch das Weglassen des Tags title + sind zwei unterschiedliche Fehler entstanden. + + Der erste Fehler besagt, daß 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, daß + das Element head ein + Element title enthalten + muß und &man.nsgmls.1; nicht + berücksichtigt, daß dieser Fehler auf dem + vorhergehenden beruht. Es wird lediglich festgestellt, + daß der Endtag von head auftritt, + obwohl nicht alle notwendigen Elemente vorhanden sind. + + + + Zum Schluß sollte der Tag + title wieder in die Beispieldatei + eingefügt werden. + + + + + + + + Die DOCTYPE-Deklaration + + Am Anfang jedes Dokuments muß der Name der dem + Dokument zugrundeliegenden DTD angegeben werden. Mit Hilfe + dieser Information können SGML-Parser die verwendete DTD + feststellen und prüfen, ob das Dokument zu ihr konform ist. + + Üblicherweise steht diese Information in einer Zeile, + die als DOCTYPE-Deklaration bezeichnet wird. + + + Eine Deklaration für ein HTML-Dokument, das nach den + Vorgaben der DTD für HTML 4.0 geschrieben wurde, sieht so + aus: + + ]]> + + und besteht aus verschiedenen Teilen. + + + + + + + + <! + + + Die Zeichenkette <! dient hier + als Indikator, daß es sich bei + diesem Ausdruck um eine SGML-Deklaration handelt und diese + Zeile den Dokumententyp festlegt. + + + + + DOCTYPE + + + Zeigt an, daß dies die SGML-Deklaration für + den Dokumententyp ist. + + + + + html + + + Nennt das erste Element, das im + Dokument auftaucht. + + + + + PUBLIC "-//W3C//DTD HTML 4.0//EN" + + + Nennt den Formalen Öffentlichen Bezeichner + + auf Englisch Formal Public + Identifier (FPI) + der DTD des Dokuments. Diese Information wird + von SGML-Parsern ausgewertet, um die von dem Dokument + referenzierte DTD zu bestimmen. + + Das Schlüsselwort PUBLIC + gehört nicht zum öffentlichen Bezeichner, + sondern legt fest, wie ein SGML-Parser die DTD finden + kann. Alternative Wege eine DTD zu referenzieren werden + später + gezeigt. + + + + + > + + + Schließt den mit <! begonnenen + Ausdruck ab. + + + + + + Formale Öffentliche Bezeichner + + + + Dieser Abschnitt braucht nicht unbedingt zu gelesen zu + werden. Dennoch ist es empfehlenswert, da er nützliche + Hintergrundinformationen enthält, die hilfreich sein + können, falls der SGML-Prozessor die genutzte DTD nicht + finden kann. + + + Jeder öffentliche Bezeichner muß eine bestimmte Syntax + haben, die wie folgt lautet: + + + + "Besitzer//Schlüsselwort Beschreibung//Sprache" + + + + Besitzer + + + Nennt den Besitzer des öffentlichen Bezeichners. + + Falls diese Zeichenkette mit ISO + beginnt, gehört der Bezeichner dem ISO-Kommitee. + Der Bezeichner "ISO 8879:1986//ENTITIES Greek + Symbols//EN" nennt ISO + 8879:1986 als den Besitzer des Satzes von + Entitäten für griechische Zeichen. ISO + 8879:1986 ist die ISO-Bezeichnung fü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 anfängliche + bzw. + -. + + Sofern am Anfang ein - steht, ist + der Bezeichner nicht öffentlich registriert, steht + hingegen ein + am Anfang, ist er + registriert. + + + + + + Im ISO-Standard ISO 9070:1991 wurde festgelegt, wie + registrierte Namen erzeugt werden können. Unter + anderem können sie von den Bezeichnungen von + ISO-Publikationen, von ISBN-Nummern oder einer + Organisationsbezeichnungen entsprechend ISO 6523 + abgeleitet werden. Anträge für neue offiziell + registrierte Bezeichner werden vom ISO-Kommitee an das + American National Standards Institute (ANSI) + weitergeleitet. + + + + + + Da das FreeBSD-Projekt seine Bezeichner nicht hat + registrieren lassen, ist der Besitzer + -//FreeBSD. Unter anderem kann man + daran auch sehen, daß das W3C sich nicht hat + registrieren lassen. + + + + + + Schlüsselwort + + + Es gibt verschiedene Schlüsselwörter mit + denen man die Art der gegebenen Informationen beschreiben + kann. Einige der üblichsten sind + DTD, ELEMENT, + ENTITIES und TEXT. + DTD wird nur für Dateien mit + DTDs verwandt, ELEMENT findet + für Dateien mit Fragmenten von DTDs Verwendung, die + nur Deklarationen für Entitäten und Elemente + enthalten. TEXT wird für + SGML-Inhalte (Texte und Tags) verwendet. + + + + + Beschreibung + + + Eine frei wählbare Beschreibung des Inhalts der + referenzierten Datei. Mö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 für + die Datei verwendete Sprache nennt. + EN steht hier für Englisch, + DE für Deutsch. + + + + + + Die <filename>catalog</filename>-Dateien + + Wenn man die oben beschriebene Syntax für + Bezeichner verwendet und ein Dokument durch einen + SGML-Prozessor schickt, muß dieser die + Möglichkeit haben, den Bezeichner auf eine real + existierende Datei abzubilden, die die benötigte DTD + enthält. + + Einer der möglichen Wege hierfür sind + Katalogdateien. Eine solche Datei, die üblicherweise + catalog heißt, besteht aus + einzelnen Zeilen, die Bezeichner auf Dateinamen abbilden. + Enthält ein Katalog beispielsweise die Zeile + + PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" + + kann ein SGML-Prozessor darüber feststellen, daß die + benötigte DTD in der Datei strict.dtd + im Unterverzeichnis 4.0 + des Verzeichnisses des Katalogs zu finden ist. + + Ein gutes Beispiel für einen Katalog ist + /usr/local/share/sgml/html/catalog. + Diese Datei enthält den Katalog für alle HTML + DTDs, die im Zuge der Installation von textproc/docproj installiert + wurden. + + + + + Die Variable <envar>SGML_CATALOG_FILES</envar> + + Natürlich muß einem SGML-Prozessor noch + mitgeteilt werden können, wo er seine Kataloge finden + kann. Viele Programme bieten hierfür + Kommandozeilenoptionen an, über die man einen oder + mehrere Kataloge angeben kann. + + Zusätzlich besteht noch die Möglichkeit mit + der Umgebungsvariablen SGML_CATALOG_FILES auf + SGML-Kataloge zu verweisen. Die Einträge von + SGML_CATALOG_FILES müssen aus den + vollständigen Pfadnamen der Kataloge, jeweils durch + Komma getrennt, bestehen. + + + + Üblicherweise werden die folgenden Kataloge über + SGML_CATALOG_FILES für + die Arbeit an den Dokumenten des FDPs eingebunden: + + + + /usr/local/share/sgml/docbook/4.1/catalog + + + + /usr/local/share/sgml/html/catalog + + + + /usr/local/share/sgml/iso8879/catalog + + + + /usr/local/share/sgml/jade/catalog + + + + Allerdings sollte das + schon geschehen + sein. + + + + + + Alternativen zu Formalen Öffentlichen Bezeichnern + + Anstatt mit einem Bezeichner die zum Dokument + gehörende DTD zu referenzieren, kann auch explizit auf + die Datei der DTD verwiesen werden. + + Die Syntax des DOCTYPE-Deklaration ist in diesem Falle + anders: + + + ]]> + + Das Schlüsselwort SYSTEM legt + fest, daß 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 öffentliche Bezeichner aus + Gründen der Portabilität bevorzugen, da man so + nicht eine Kopie der DTD mit dem Dokument selber verteilen + muß, beziehungsweise da man, wenn man mit + SYSTEM arbeitet, nicht davon ausgehen kann, + daß die benötigte DTD auf anderen Systemen genau + unter dem gleichen Pfad verfügbar ist. + + + + + + Die Rückkehr zu SGML + + An einer früheren Stelle wurde erwähnt, daß + man SGML nur benötigt, falls man selbst eine DTD entwickeln + möchte. Genaugenommen ist das nicht 100%ig richtig. Einige + Teile der SGML-Syntax können auch in normalen Dokumenten + verwendet werden, falls dies gewünscht oder notwendig + ist. + + In diesem Falle muß dafür Sorge getragen werden, + daß ein SGML-Prozessor feststellen kann, daß ein + bestimmter Abschnitt des Inhalts SGML ist, das er verarbeiteten + muß. + + 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 für SGML, das in Dokumenten verwendet + werden muß… + + + + + Kommentare + + Kommentare sind SGML-Konstrukte, die normalerweise nur + in DTDs gültig sind. Dennoch ist es, wie in + gezeigt, + möglich Fragmente mit SGML-Syntax in Dokumenten zu + verwenden. + + Zum Abgrenzen von SGML-Kommentaren wird ein doppelter + Bindestrich -- verwendet. Mit + seinem ersten Auftreten öffnet er einen Kommentar, mit + seinem zweiten schließt er ihn wieder. + + + Beispiele für Kommentare in SGML + + <!-- Testkommentar --> + + + + + + + +]]> + + + + + Es sind zwei Bindestriche + + Es gibt ein Problem mit den PostScript- oder + PDF-Versionen dieses Dokuments. Das obige Beispiel + zeigt vielleicht nur einen Bindestrich (-) + hinter <! und vor + >. + + Es müssen zwei Bindestriche + und nicht nur einer benutzt werden. + Die PostScript- und PDF-Versionen haben vielleicht + beide Bindestriche zu einem längeren Strich, dem + em-dash, zusammengefaßt. + + Die HTML-, nur-Text und RTF-Versionen dieses Dokuments + sind nicht von diesem Problem betroffen. + + ]]> + + Hat man früher schon Erfahrungen mit HTML gesammelt, + wird man vielleicht andere Regeln für den Gebrauch von + Kommentaren kennengelernt haben. Beispielsweise wird oft + angenommen, daß 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. + + + Fehlerhafte SGML-Kommentare + + ]]> + + SGML-Parser würden die mittlere Zeile wie folgt + interpretieren: + + + <!DIES IST NICHT TEIL EINES KOMMENTARS> + + Da es sich hierbei nicht um gültiges SGML handelt, kann + diese Zeile zur verwirrenden Fehlermeldungen führen. + + ]]> + + 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. + + + + + Fingerübungen… + + + + Zur Übung können Sie einige Kommentare in + die Datei beispiel.sgml einfügen + und überprüfen, ob die Datei nun noch erfolgreich + von &man.nsgmls.1; validiert werden kann. + + + + Zu Testzwecken sollten Sie + auch noch ein paar fehlerhafte Kommentare hinzufügen + und sich die resultierenden Fehlermeldungen von + &man.nsgmls.1; ansehen. + + + + + + + Entitäten + + Entitäten stellen einen Mechanismus dar, mit dem + einzelnen Dokumententeilen ein Name zugewiesen werden kann. + Findet ein SGML-Parser während des Parsens eine + Entität, ersetzt er diese durch den ihr zugewiesenen + Inhalt. + + Dadurch steht eine einfache Möglichkeit zur + Verfügung, mit der variabler Inhalt in SGML-Dokumenten + eingebunden werden kann. Zusätzlich sind Entitäten der + einzige Weg, über den eine Datei in eine andere Datei mit + SGML-Mitteln eingebunden werden kann. + + Es werden zwei Arten von Entitäten unterschieden: + Allgemeine Entitäten und + Parameterentitäten. + + + Allgemeine Entitäten + + Allgemeine Entitäten können nur in + Dokumenten benutzt werden. Sie können zwar im + SGML-Kontext definiert aber dort nicht benutzt + werden. Vergleichen Sie dies mit + Im Parameterentitäten. + + Jede allgemeine Entität hat einen Namen, über + den sie angesprochen werden kann, um den von ihr + referenzierten Inhalt in ein Dokument einzubinden. Dafür + muß an der betreffenden Stelle der Namen der + Entität per + &entitaetenname; + einfügt werden. Eine Entität + current.version könnte beispielsweise + durch die aktuelle Versionsnummer eines Programms ersetzt + werden. Man könnte also schreiben: + + + + + + Die aktuelle Version des + Programms ist ¤t.version;.]]> + + Wenn sich die Versionsnummer ändert, muß + nur die Entität angepaßt und anschließend + das Dokument neu erzeugt werden. + + Eine weitere Einsatzmöglichkeit für Allgemeine + Entitäten ist das Einbinden von Zeichen, die auf andere + Weise nicht in ein SGML-Dokument eingefügt werden + könnten. Ein Beispiel für solche Zeichen sind + < und &, die normalerweise nicht direkt in + SGML-Dokumenten erlaubt sind. Stößt ein SGML-Parser + bei seiner Arbeit auf das Symbol <, nimmt er an, daß + der Anfang eines Start- oder Endtags gefunden wurde. Bei einem + & wird er annehmen, den Anfang einer Entität gefunden + zu haben. + + Wenn eines der beiden Zeichen benötigt wird, werden + die allgemeinen Entitäten &lt; und &amp; + verwendet. + + Allgemeine Entitäten können nur in einem + SGML-Kontext definiert werden. Üblich ist es, dies direkt + nach der DOCTYPE-Deklaration zu tun: + + + Allgemeine Entitäten festlegen + + + +]>]]> + + Wichtig ist an dieser Stelle, daß die + DOCTYPE-Deklaration durch eine eckige Klammer am Ende der + ersten Zeile erweitert wurde. Die beiden Entitä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, daß + man die über DOCTYPE genannte DTD erweitern möchte. + + + + + + Parameterentitäten + + Genau wie Allgemeine + Entitäten werden Parameterentitäten + eingesetzt um wiederverwendbare Inhaltsteile mit Namen zu + versehen. Im Gegensatz zu Allgemeinen Entitäten + können sie aber nur innerhalb eines SGML-Kontextes + genutzt werden. + + Die Definition von Parameterentitäten erfolgt + ähnlich zu der Allgemeiner Entitäten. Sie werden + lediglich mit + %entitaetenname; + anstelle von + &entitaetenname; + referenziert + Es wird das Prozentzeichen anstelle des + kaufmännischen Unds verwendet. + . Wichtig ist, daß das + %-Zeichen zwischen + ENTITY und dem Entitätennamen ein Teil + der Definition ist. + + + Parameterentitäten festlegen + + + + + + +]>]]> + + + + + + + + Fingerübungen… + + + + Fügen Sie in beispiel.sgml + eine Allgemeine Entität ein. + + +]> + + + + Eine HTML-Beispieldatei + + + +

Das ist ein Absatz mit etwas Text.

+ +

Das ist ein Absatz mit anderem Text.

+ +

Dieser Absatz wird rechtsbündig + ausgerichtet.

+ +

Die aktuelle Version ist: &version;

+ +]]> + + + + Validieren Sie diese Datei mit &man.nsgmls.1; + + + + Öffnen Sie nun beispiel.sgml + mit Ihrem Webbrowser. Es kann notwendig sein, daß + Sie die Datei vorher in beispiel.html + umbenennen müssen, damit die Datei auch als + HTML-Dokument erkannt wird. + + Nur wenn Sie einen sehr modernen Browser haben, werden + Sie sehen können, daß + &version; durch die Versionsnummer + ersetzt wurde. Leider haben die meisten Webbrowser + sehr einfache SGML-Parser, die nicht richtig mit SGML + umgehen können + Eigentlich ist das eine Schande. Man stelle sich + vor, welche Probleme und Hacks, wie beispielsweise + Server Side Includes, man an dieser Stelle hätte + vermeiden können. + . + + + + Die Lösung hierfür ist, das Dokument zu + normalisieren. Zu diesem Zweck liest + ein Normer + das Dokument ein und gibt anschließend semantisch + gleichwertiges SGML wieder aus, daß auf verschiedene + Arten transformiert worden sein kann. Eine dieser + möglichen Transformationen ist das Ersetzen der + Referenzen auf Entitäten mit dem von ihnen + präsentierten Inhalt. + + Versuchen Sie die Beispieldatei mittels &man.sgmlnorm.1; + zu normalisieren: + + + + &prompt.user; sgmlnorm beispiel.sgml > beispiel.html + + Anschließend sollten Sie eine normalisierte + Version, daß heißt eine, bei der die + Entitäten gegen ihren Inhalt ersetzt wurden, in der + Datei beispiel.html finden. Diese + Datei können Sie sich nun mit Ihrem Browser + ansehen. + + + + + Wenn Sie sich die Ausgaben von &man.sgmlnorm.1; ansehen, + werden Sie feststellen, daß die DOCTYPE-Deklaration am + Anfang der Datei nicht mehr enthalten ist. Möchten Sie + die Deklaration behalten, muß &man.sgmlnorm.1; mit der Option + aufrufen werden: + + &prompt.user; sgmlnorm -d beispiel.sgml > beispiel.html + + + + + + + Dateien mit Entitäten einbinden + + + + Sowohl Allgemeine als + auch Parameterentitäten + sind nützliche Helfer, wenn es darum geht, eine Datei in + eine andere einzubinden. + + + Dateien mit Allgemeinen Entitäten einbinden + + Angenommen man hat ein Buch geschrieben, dessen Inhalt + auf mehrere Dateien aufgeteilt und mittels SGML + ausgezeichnet. Jedes Kapitel wurde dazu in einer eigenen Datei + (kapitel1.sgml, + kapitel2.sgml usw.) abgelegt und + über eine Datei buch.sgml sollen + alle physischen Dateien wieder mit der Hilfe von + Entitäten zu einem logischen Dokument + zusammengeführt werden. + + Damit der Inhalt der Dateien mit Entitäten + eingebunden werden kann, muß die Deklaration der + Entitäten das Schlüsselwort + SYSTEM enthalten. SGML-Parser werden so + angewiesen, den Inhalt der referenzierten Datei als Wert + für die jeweilige Entität zu nehmen. + + + Dateien mit Allgemeinen Entitäten einbinden + + + + + +]> + + + + + &kapitel.1; + &kapitel.2; + &kapitel.3; +]]> + + + + Wenn man Allgemeine Entitäten benutzt, um andere + Dateien einzubinden, dürfen diese Dateien + (kapitel1.sgml, + kapitel2.sgml, ...) + keine eigene DOCTYPE-Deklaration + haben. + + + + + Dateien mit Parameterentitäten einbinden + + Wie bereits festgestellt, können + Parameterentitäten nur innerhalb eines SGML-Kontexts + genutzt werden. Warum möchte man aber Dateien innerhalb + eines SGML-Kontexts einbinden? Der Vorteil liegt in der + Möglichkeit, die Deklaration von Entitäten in eine + andere Datei auslagern zu kö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 Möglichkeit wäre es, die dafür notwendigen + Entitäten am Anfang jedes Buches einzeln festzulegen + – was allerdings mit der Zeit unhandlich und + fehlerträchtig wird. + + Alternativ bietet sich dazu an, die Deklarationen in eine + separate Datei auszulagern und deren Inhalt anschließend + in beide Bücher über Parameterentitäten + einzubinden. + + + Dateien mit Parameterentitäten einbinden + + Zuerst werden die Entitäten in einer separaten + Datei namens kapitel.ent deklariert. + kapitel.ent enthält für + dieses Beispiel die folgenden Zeilen: + + + +]]> + + Im zweiten Schritt fügt man in beide Bücher + eine Parameterentität ein, die den Inhalt von + kapitel.ent referenziert, und lädt + über diese dann die Deklarationen. Anschließend + können die so geladenen Entitäten wie gewohnt + genutzt werden. + + + + + + +%kapitel; +]> + + + &kapitel.1; + &kapitel.2; + &kapitel.3; +]]> + + + + + Fingerübungen… + + + Binden Sie Dateien über Allgemeine Entitäten ein + + + + Legen Sie drei Dateien (absatz1.sgml, + absatz2.sgml und absatz3.sgml) + mit jeweils einer Zeile wie + + + + + + Erster Absatz.

]]> + an. + + + + Ändern Sie beispiel.sgml so ab, daß sie wie folgt + aussieht: + + + + + +]> + + + + Eine HTML-Beispieldatei + + + +

Die aktuelle Version dieses Dokuments ist &version;

+ + &absatz1; + &absatz2; + &absatz3; + +]]> + + + + Erzeugen Sie nun die Datei + beispiel.html, indem Sie + beispiel.sgml normalisieren: + + &prompt.user; sgmlnorm -d beispiel.sgml > beispiel.html + + + + Öffnen Sie beispiel.html + nun mit einem Webbrowser und vergewissern Sie sich, + daß der Inhalt der Dateien + absatzN.sgml + in beispiel.html übernommen + wurde. + + + + + + Binden Sie Dateien mit Parameterentitäten ein + + + Hierfür müssen Sie die vorherige Fingerübung gemacht haben. + + + + + Ändern Sie beispiel.sgml so ab, daß es wie + folgt aussieht: + + %entitaeten; +]> + + + + Eine HTML-Beispieldatei + + + +

Die aktuelle Version dieses Dokuments ist &version;

+ + &absatz1; + &absatz2; + &absatz3; + +]]> + + + + Legen Sie eine weitere Datei entitaeten.sgml an, + die folgenden Inhalt hat: + + + + +]]> + + + + Erzeugen Sie die Datei + beispiel.html, indem Sie + beispiel.sgml normalisieren: + + &prompt.user; sgmlnorm -d beispiel.sgml > beispiel.html + + + + Öffnen Sie beispiel.html + nun mit einem Webbrowser und vergewissern Sie sich, + daß der Inhalt der Dateien + absatzN.sgml + in beispiel.html übernommen + wurde. + + + + + + + + Markierte Bereiche + + SGML erlaubt es, daß bestimmte Dokumentabschnitte + während der Verarbeitung besonders behandelt werden sollen. + Diese Abschnitte werden als markierte Bereiche + auf Englisch marked + sections + + bezeichnet. + + + Aufbau eines markierten Bereiches + + <![ SCHLÜ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 + SCHLÜSSELWORT legt fest, wie der + markierte Inhalt durch einen SGML-Prozessor + während der Verarbeitung behandelt werden soll. Der + markierte Inhalt selbst beginnt erst nach der + zweiten eckigen Klammer und erstreckt sich bis zu den zwei + schließenden eckigen Klammern am Ende des Bereiches. Mit + Hilfe des > Zeichens wird der mit + <! begonnene SGML-Kontext wieder + verlassen. + + + Schlüsselworte für markierte Bereiche + + + <literal>CDATA</literal> und <literal>RCDATA</literal> + + Die Schlüsselworte CDATA und + RCDATA bestimmen das + Inhaltsmodell für markierte + Bereiche. Dadurch ist es möglich, vom Standardmodell + abzuweichen. + + Ein SGML-Prozessor muß wä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 nützlichsten Inhaltsmodelle. + CDATA steht für + Zeichendaten + auf Englisch character + data. Trifft ein + Parser auf dieses Inhaltsmodell, wird er annehmen, daß + sich im zugehörigen Dokumentenbereich nur + gewöhnliche Zeichen befinden. Das + bedeutet, daß < und & ihre besondere Bedeutung + verlieren und als einfache Zeichen behandelt werden. + + RCDATA steht für + Entitätenreferenzen und Zeichendatenauf + Englisch + Entity references and character + data. Für einen + Bereich mit diesem Inhaltsmodell, wird ein Parser davon + ausgehen, daß er sowohl Zeichen als auch + Enitätenreferenzen finden kann. < verliert hier zwar + auch seine besondere Bedeutung, doch & wird weiterhin + als Anfang einer Entität interpretiert. + + Nützlich ist das CDATA-Modell + vor allem dann, wenn es darum geht Texte eins-zu-eins zu + übernehmen, in denen < und & gehäuft + auftreten. Zwar kann man solche Texte überarbeiten und + jedes < durch ein &lt; und jedes & durch ein + &amp; ersetzen, doch es wird in den meisten Fällen + einfacher sein, für den betreffenden Text + CDATA als Inhaltsmodell festzulegen. Ein + SGML-Parser wird dann, sobald er auf < und & trifft, + diese als Zeichen in einem Text betrachten. + + + Bei der Verwendung von CDATA und + RCDATA als Inhaltsmodell für + SGML-Beispiele, wie sie in diesem Dokument enthalten sind, + muß bedacht werden, daß der Inhalt eines + CDATA-Bereiches nicht validiert wird. + Daß das SGML in diesen Bereichen gültig ist, + muß auf andere Weise sichergestellt werden. Denkbar ist + beispielsweise, es in einem separaten Dokument zu + erstellen, dort zu prüfen und erst dann in das + eigentliche Dokument einzufügen. + + + + + CDATA als Inhaltsmodell für markierte Bereiche + + <para>Das ist ein Beispiel, wie man einen Text, + der viele &lt; und &amp; Entitäten enthält, in ein + Dokument einbinden kann. + Das Beispiel selbst, das sich innerhalb des markierten Bereiches befindet, + ist ein HTML-Fragment. Der diesen Text umschließende Tag, beginnend mit + mit para und endend mit /para, stammt aus der DocBook DTD.</para> + +<programlisting> + <![ RCDATA [ Dieses Beispiel demonstriert die Verwendung von HTML-Elementen. + Da spitze Klammern so oft vorkommen, ist es einfacher, das + gesamte Beispiel als CDATA Abschnitt auszuweisen, als die + entsprechenden Entitäten zu nutzen.

+ +
    +
  • Das ist ein Listenelement.
    • +
  • Das ist ein zweites Listenelement.
    • +
  • Das ist ein drittes Listenelement.
    • +
+ +

Und das hier, das ist das Ende des Beispiels.

]]> + ]]> +</programlisting> + + Liest man die Quellen dieser Fibel, wird man + feststellen, daß diese Technik durchgängig + angewandt wurde. + + + + + + <literal>INCLUDE</literal> und + <literal>IGNORE</literal> + + Das Schlüsselwort INCLUDE legt + fest, daß der Inhalt des betreffenden Abschnittes + mitverarbeitet wird. Demgegenüber bestimmt + IGNORE, daß er ignoriert wird, + daß heißt, daß er bei der Verarbeitung + übergangen wird und in der Ausgabe nicht enthalten + ist. + + + Anwendung von <literal>INCLUDE</literal> und + <literal>IGNORE</literal> in markierten + Abschnitten + + <![ INCLUDE [ + Dieser Text wird verarbeitet und eingebunden. +]]> + +<![ IGNORE [ + Dieser Text wird weder verarbeitet noch eingebunden. +]]> + + + Für sich alleine ist IGNORE als + Anweisung nicht besonders nützlich, da ein Bereich, der + von der Verarbeitung ausgenommen sein soll, auch + auskommentiert werden kann. + + Kombiniert man IGNORE hingegen mit + Parameterentitäten, + steht so ein Weg zur Verfügung, um dessen Anwendung + besser steuern zu können. Zwar können + Parameterentitäten nur in einem SGML-Kontext einsetzt + werden, da aber markierte Bereiche ebenfalls SGML-Konstrukte + sind, ist diese Einschränkung irrelevant. + + Soll beispielsweise ein und dasselbe Dokument in zwei + unterschiedlichen Varianten produziert werden, einer + gedruckten und einer digitalen, und soll nur die digitale + zusätzliche Informationen enthalten, kann dies mit + einem Trick erreicht werden. + + Man definiert eine Parameterentitä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 Schlüsselwort die zuvor definierte + Parameterentität ein. + + Soll anstelle der digitalen die gedruckte Variante + produziert werden, muß lediglich der Entität + IGNORE als Wert zugewiesen und das + Ursprungsdokument erneut durch den SGML-Prozessor geschickt + werden. + + + Kontrolle von markierten Bereichen über + Parameterentitä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 muß + der Wert der Entität geändert werden. + + <!ENTITY % digitale.kopie "IGNORE"> + + Bei der Verarbeitung wird als Schlüsselwort in + beiden Fällen der von + %digitale.kopie repräsentierte + Wert verwendet. Im ersten Fall wird der Inhalt des + markierten Bereichs mitverarbeitet, im zweiten Fall + nicht. + + + + + + + Fingerübung… + + + + Legen Sie eine neue Datei + abschnitt.sgml an, die folgenden + Inhalt hat: + + <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!ENTITY % text.ausgabe "INCLUDE"> +]> + +<html> + <head> + <title>Ein Beispiel mit markierten Abschnitten</title> + </head> + + <body> + <p>Dieser Absatz <![ CDATA [beinhaltet viele < + Zeichen (< < < < <). Weshalb es einfacher ist, + ihn als CDATA Bereich auszuweisen. ]></p> + + <![ IGNORE [ + <p>Dieser Absatz wird NICHT in der Ausgabe enthalten sein.</p> + ]]> + + <![ [ + <p>Dieser Absatz wird in Abhängigkeit von %text.ausgabe + mitausgegeben.</p> + ]]> + </body> +</html> + + + + Normalisieren Sie den Inhalt dieser Datei mit Hilfe + von &man.sgmlnorm.1; und sehen Sie sich das Ergebnis an. + Achten Sie dabei darauf, welche Absätze enthalten beziehungsweise + nicht enthalten sind und was aus den + CDATA-Bereichen geworden ist. + + + + Ändern Sie die Definition von + text.ausgabe so, daß es den + Wert IGNORE zugewiesen bekommt. + Verarbeiten Sie dann die Datei erneut mit &man.sgmlnorm.1; + und vergleichen die Ausgabe mit der vom ersten + &man.sgmlnorm.1; Lauf. + + + + + + + + Schlußbemerkung + + Aus Platzgründen, und um der Verständlichkeit + Willen, wurden viele Gesichtspunkte nicht in aller Tiefe + beziehungsweise gar nicht besprochen. Trotzdem sollte in den + bisherigen Kapiteln genügend Wissen über SGML + vermittelt worden sein, um den Aufbau der Dokumentation des FDPs + zu verstehen. + + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/structure/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/structure/chapter.sgml new file mode 100644 index 0000000000..ec525e1778 --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/structure/chapter.sgml @@ -0,0 +1,54 @@ + + + + # Verzeichnisstruktur unter <filename>doc/</filename> + + Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie + bitte + das Original in englischer Sprache. + + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml new file mode 100644 index 0000000000..3c9972dcf5 --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml @@ -0,0 +1,53 @@ + + + + #* Die Stylesheets + + Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie + bitte + das Original in englischer Sprache. + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/the-website/chapter.sgml new file mode 100644 index 0000000000..9a79f241ba --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/the-website/chapter.sgml @@ -0,0 +1,53 @@ + + + + # Die Webseite + + Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie + bitte + das Original in englischer Sprache. + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/tools/chapter.sgml new file mode 100644 index 0000000000..e24b0c108f --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/tools/chapter.sgml @@ -0,0 +1,363 @@ + + + + Die Werkzeuge + + Innerhalb des FDPs werden verschiedene Programme für die + Verwaltung der FreeBSD-Dokumentation, ihrer Transformation in + verschiede Formate und weitere Aufgaben eingesetzt. Wer an der + FreeBSD-Dokumentation mitarbeiten möchte, wird diese + Programme benötigen. + + Doch dies ist kein Grund zur Angst, da alle notwendigen + Programme als FreeBSD-Ports und fertige Pakete vorhanden sind, + wodurch sich die Installation drastisch vereinfacht. + + Allerdings müssen diese Programme installiert werden, + bevor alle Beispiele der folgenden Kapitel ausprobiert werden + können. + + + + Wenn es möglich ist, sollte der Port + <filename role="package">textproc/docproj</filename> + verwendet werden + + + Durch die Installation des Ports textproc/docproj kann die + Installation vereinfacht und eine Menge Zeit gespart werden. Bei + diesem Port handelt es sich um einen + Metaport, der selbst keine Programme oder + ähnliches installiert. Stattdessen enthält er eine + Vielzahl von Abhängigkeiten zu anderen Ports und setzt + deren korrekte Installation voraus. Durch seine Installation + sollten automatisch alle Pakete, die in + diesem Kapitel genannt werden, auf den Rechner geladen und dort + installiert werden. + + Ein nur unter bestimmten Umständen benötigter Port + ist das JadeTeX-Makro-Paket, das seinerseits eine + TeX-Installation voraussetzt. TeX ist ein ziemlich großes + Programmpaket und sollte nur installiert werden, sofern + Zieldokumente im PostScript- oder PDF-Format generiert werden + sollen. + + Um den Platz und die Zeit für die Installation von + JadeTeX und TeX zu sparen, muß bei der Installation + angeben werden, ob JadeTeX (und damit auch Tex) installiert + werden soll oder nicht. + + Daher sollte der docproj-Port entweder mit + + &prompt.root; make JADETEX=yes install + + oder mit + + &prompt.root; make JADETEX=no install + + installiert werden, je nachdem was gewünscht wird. + Bedacht werden sollte, daß wenn der Port mit mit + JADETEX=no installiert wird, nur die + Formate HTML und ASCII erzeugen können. Für + PostScript und PDF wird TeX benötigt. + + + + Notwendige Werkzeuge + + + Software + + Die folgenden Programme sind notwendig, bevor man sinnvoll + an der FreeBSD-Dokumentation arbeiten und diese in andere + Formate wie HTML, reinen Text und RTF umwandeln kann. + + + + + + + + + SP + (textproc/sp) + + + Eine Gruppe von Anwendungen, einschließlich + eines validierenden SGML-Parsers und eines + SGML-Normers. + + + + + Jade (textproc/jade) + + + Eine DSSSL-Implementierung. Sie wird gebraucht, um + Dokumente in andere Formate wie HTML und TeX zu + übersetzen. + + + + + Tidy + (www/tidy) + + + Ein Formatierer, mit dem man Teile der automatisch + generierten HTML-Dateien neuformatieren kann, um ihre + Lesbarkeit zu erhöhen. + + + + + + + Links (www/links) + + + Ein Textbrowser, der HTML-Dateien in einfache Textdateien + umwandeln kann. + + + + + peps + (graphics/peps) + + + Einige der Dokumente enthalten Grafiken, die nur im + EPS-Format vorliegen. Damit diese von dem meisten + Webbrowsern angezeigt werden können, müssen + sie nach PNG konvertiert werden. + + + + + + + Die DTDs und die Entitäten + + Das FDP benutzt verschiedene DTDs und + Entitätensätze, die installiert sein müssen, + bevor mit der Arbeit an einem beliebigen Dokument begonnen + werden kann. + + + + HTML DTD (textproc/html) + + + HTML ist die bevorzugte + Auszeichnungssprache des World Wide Web und wird + durchgängig für die FreeBSD-Webseite + genutzt. + + + + + DocBook DTD (textproc/docbook) + + + DocBook ist als Auszeichnungssprache für + technische Dokumentationen entwickelt worden. Die + gesamte FreeBSD-Dokumentation wird mittels DocBook + erstellt. + + + + + ISO 8879-Entitäten + (textproc/iso8879) + + + 19 der ISO 8879:1986-Zeichensätze, die von + vielen DTDs benötigt werden. Darin enthalten sind + mathematische Symbole, zusätzliche Zeichen, die + für auf dem lateinischen beruhende Alphabete + benötigt werden und griechische Zeichen. + + + + + + + + + Die Stilvorlagen + + Die Stilvorlagen werden während der Transformation und + der Formatierung von Dokumenten, beispielsweise für die + Bildschirmdarstellung oder den Druck, benutzt. + + + + Modular DocBook Stylesheets (textproc/dsssl-docbook-modular) + + + Die Modular DocBook Stylesheets werden + benötigt, wenn mittels DocBook erstellte Dokumente + in Formate wie HTML oder RTF konvertiert werden + sollen. + + + + + + + + Optionale Werkzeuge + + Die in diesem Kapitel genannten Programme müssen nicht + unbedingt installiert werden. Allerdings können sie die + Arbeit an der Dokumentation erleichtern und die Anzahl an + möglichen Ausgabeformaten erhöhen. + + + Software + + + + JadeTeX und + teTeX (print/jadetex und print/teTeX) + + + Jade und + teTeX werden eingesetzt, um + DocBook-Dokumente nach DVI, Postscript und PDF zu + konvertieren. Hierfür müssen die + JadeTeX Makros installiert + sein. + + Ist es nicht geplant, die Dokumente in einem dieser + Formate zu erzeugen, wenn also HTML, Text und RTF + ausreichend sind, brauchen + JadeTeX und + teTeX nicht installiert zu + werden. Da die Installation von + teTeX insgesamt 30 MB + benötigt, kann so Zeit und Plattenplatz gespart + werden. + + + + Wird sich für die Installation von + JadeTeX und + teTeX entschieden, + muß teTeX + anschließend noch eingerichtet werden. Die Datei + print/jadetex/pkg-message + enthält detailierte Angaben zu den dafür + notwendigen Schritten. + + + + + + + Emacs oder + XEmacs (editors/emacs oder editors/xemacs) + + + Beide Texteditoren haben einen speziellen Modus zur + Bearbeitung von SGML-Dokumenten entsprechend den + Vorgaben einer SGML-DTD. Zusätzlich bieten sie + Funktionen an, mit denen sich der Tippaufwand reduzieren + und Fehlerwahrscheinlichkeit senken + läßt. + + + + Natürlich muß nicht mit einem dieser + Texteditoren gearbeitet werden; jeder andere Editor kann + dafür genausogut genutzt werden, doch vielleicht + wird die Arbeit durch sie als effektiver empfunden + werden. + + + + + + + + + Sofern Sie Vorschläge haben, welche andere + Software für die Verarbeitung oder Bearbeitung von + SGML-Dokumenten in diese Liste mitaufgenommen werden sollte, + senden Sie diese bitte an &a.nik;. + + + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/translations/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/translations/chapter.sgml new file mode 100644 index 0000000000..8770d2792b --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/translations/chapter.sgml @@ -0,0 +1,53 @@ + + + + # Übersetzungen in andere Sprachen + + Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie + bitte + das Original in englischer Sprache. + + + + diff --git a/de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml new file mode 100644 index 0000000000..16e3c3fedc --- /dev/null +++ b/de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml @@ -0,0 +1,54 @@ + + + + # Der Schreibstil + + Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie + bitte + das Original in englischer Sprache. + + + + +