Die Fibel für neue Mitarbeiter des FreeBSD-Dokumentationsprojekts

diff --git a/de_DE.ISO8859-1/books/fdp-primer/book.sgml b/de_DE.ISO8859-1/books/fdp-primer/book.sgml index 4fecc363e1..722cddb0be 100644 --- a/de_DE.ISO8859-1/books/fdp-primer/book.sgml +++ b/de_DE.ISO8859-1/books/fdp-primer/book.sgml @@ -1,349 +1,291 @@ -%authors; - - -%translators; - - -%mailing-lists; - - -%man; - - -%urls; - + +%books.ent; %chapters; - - ]> Die Fibel für neue Mitarbeiter des FreeBSD-Dokumentationsprojekts - - Nik - Clayton - -

nik@FreeBSD.org

- - + The FreeBSD German Documentation Project 1998 1999 2000 2001 2002 2003 2004 - Nik Clayton + The FreeBSD German Documentation Project $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. - - + &bookinfo.legalnotice; 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 + Bitte beachten Sie, dass diese Fibel + jederzeit unter Bearbeitung und noch + nicht vollständig ist. Die noch nicht übersetzten 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 + 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. + Ausgabe auf dem Bildschirm. &prompt.user; su Paßwort: Referenzen auf Hilfeseiten. Mit su 1 - können Sie sich als anderer + können Sie sich als ein 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 + 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/overview/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/overview/chapter.sgml index 002116a572..e029aeaed5 100644 --- a/de_DE.ISO8859-1/books/fdp-primer/overview/chapter.sgml +++ b/de_DE.ISO8859-1/books/fdp-primer/overview/chapter.sgml @@ -1,348 +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 + verwaltet. Das bedeutet, dass 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 + Für den Fall, dass 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 + dass zeitaufwändige 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 + dass 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 index 42b3e680c1..0941bdeaef 100644 --- a/de_DE.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml +++ b/de_DE.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml @@ -1,206 +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 + ein so genannter 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 + dass 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/sgml-primer/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml index 89ae2592fd..c2e2979cdf 100644 --- a/de_DE.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml +++ b/de_DE.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -1,1983 +1,1969 @@ 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 + 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. - - - 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 + Für viele Zwecke war dies allerdings nicht ausreichend. + Von einem machinenlesbaren Text wird erwartet, dass er auch von + Maschinen gelesen und intelligent weiterverarbeitet werden kann. + Einzelne Stellen sollen hervorgehoben werden, andere sollen in ein Glossar aufgenommen werden oder auf andere Textstellen verweisen. Dateinamen wiederum sollen in einer 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 + Bildschirm dargestellt werden, der Ausdruck soll jedoch in + Schrägschrift oder in einer beliebigen anderen + Darstellungsform erfolgen. + + Anfänglich gab es die Hoffnung, dass 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 + zu erreichen. Computer sollte den Text lesen und dazu in der Lage + sein, selbstständig wichtige Formulierungen, Dateinamen, + Benutzereingaben oder Beispiele zu erkennen. Leider verlief die + Entwicklung in diesem Bereich nicht wie gewünscht und Computer + benötigen nach wie vor etwas Unterstützung, bevor sie + Texte vernünftig verarbeiten können. + + Genauer gesagt, man muss 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ß + gesprochen. bedeutet, dass 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 + dass 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 + verbergen, um zu vermeiden, dass 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 + des Dokuments. Allerdings muss 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. + Die Einfü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. 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 + Dokuments, dass 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 + Es ist anzunehmen, dass, 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 + dass 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 + Kapitel, die wiederum selbst 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 + Anzumerken ist an dieser Stelle, dass das eben gesagte ohne weiteres auf jeden Inhaltstyp angewandt werden kann, auch - ohne daß von SGML die Rede ist. Man + ohne dass 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 + Deshalb muss 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 + und DocBook werden dafür so genannte 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 + festzulegen, dass 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 + haben. Ebenso ist es nicht notwendig, dass Elemente einen Inhalt haben. Beispielsweise kann in HTML-Dokumenten mittels - eines speziellen Elements festgelegt werden, daß eine + 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 benötigt. Verwendung eines Elements (nur Starttag) In HTML kann man mit dem Element hr - festlegen, daß an einer bestimmten Stelle eine + festlegen, dass 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 gesprochen wird, ist damit der Text gemeint, der aus den drei Zeichen <, p und > besteht. Wird hingegen von dem Element 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 Attributwert doppelte Anführungszeichen ("), wird der Wert in einfachen Anführungszeichen eingeschlossen. Attribute mit einfachen Anführungszeichen Ich stehe rechts!

]]> Manchmal können die Anführungszeichen um den Attributwert weggelassen werden. Allerdings sind die Regeln, die festlegen wann dies zulässig ist, sehr spitzfindig. Am besten schließen Sie Attributwerte immer in Anführungszeichen ein. 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ß… + Was dafür getan werden muss;… Damit die Beispiele dieser Fibel ausgeführt werden - können, ist es notwendig, daß einige Programme auf + können, ist es notwendig, dass 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 + Anschließend muss 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. + Damit die Änderungen wirksam werden, meldet man + sich ab und anschließend wieder an – oder man + führt die obigen Anweisungen direkt in der Shell + aus und setzt so die benötigten Umgebungsvariablen. 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 + ist nsgmls - ein validierender Parser. + nsgmls 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 + Wird nsgmls 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 + So prüft man mit nsgmls, 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 + nsgmls ohne jegliche Ausgabe beenden. Das bedeutet, + dass 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. + Die Fehlermeldungen, die von nsgmls + 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 + 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, daß + Der zweite Fehler wurde dadurch verursacht, dass das Element head ein Element title enthalten - muß und &man.nsgmls.1; nicht - berücksichtigt, daß dieser Fehler auf dem + muss und nsgmls + nicht berücksichtigt, dass dieser Fehler auf dem vorhergehenden beruht. Es wird lediglich festgestellt, - daß der Endtag von head auftritt, + dass 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 + Am Anfang jedes Dokuments muss 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 + als Indikator, dass 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 + Zeigt an, dass 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 + Jeder öffentliche Bezeichner muss 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 + daran auch sehen, dass 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 + SGML-Prozessor schickt, muss 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 + kann ein SGML-Prozessor darüber feststellen, dass 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 + Natürlich muss 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 + 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 ö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 + muss, beziehungsweise da man, wenn man mit SYSTEM arbeitet, nicht davon ausgehen kann, - daß die benötigte DTD auf anderen Systemen genau + dass 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ß + An einer früheren Stelle wurde erwähnt, dass 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 + In diesem Falle muss dafür Sorge getragen werden, + dass ein SGML-Prozessor feststellen kann, dass ein bestimmter Abschnitt des Inhalts SGML ist, das er verarbeiteten - muß. + 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 für SGML, das in Dokumenten verwendet - werden muß… + werden muss… 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  ]]> 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  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. + von nsgmls 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. + nsgmls 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 + muss 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ß + Wenn sich die Versionsnummer ändert, muss 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ß + 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 Entität gefunden zu haben. Wenn eines der beiden Zeichen benötigt wird, werden die allgemeinen Entitäten < und & 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 + Wichtig ist an dieser Stelle, dass 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ß + Die eckigen Klammern sind notwendig um festzulegen, dass 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 + . Wichtig ist, dass 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; + Validieren Sie diese Datei mit + nsgmls Öffnen Sie nun beispiel.sgml - mit Ihrem Webbrowser. Es kann notwendig sein, daß + mit Ihrem Webbrowser. Es kann notwendig sein, dass 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ß + Sie sehen können, dass &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 + gleichwertiges SGML wieder aus, dass 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: - - + Versuchen Sie, die Beispieldatei mittels + sgmlnorm zu normalisieren: &prompt.user; sgmlnorm beispiel.sgml > beispiel.html Anschließend sollten Sie eine normalisierte - Version, daß heißt eine, bei der die + Version, dass 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 + Wenn Sie sich die Ausgaben von sgmlnorm + ansehen, werden Sie feststellen, dass + die DOCTYPE-Deklaration am Anfang der Datei nicht mehr + enthalten ist. Möchten Sie die Deklaration behalten, + muss sgmlnorm 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 + eingebunden werden kann, muss 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: + Ändern Sie beispiel.sgml so + ab, dass 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 + dass 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: + Ändern Sie beispiel.sgml so + ab, dass 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 + dass der Inhalt der Dateien absatzN.sgml in beispiel.html übernommen wurde. Markierte Bereiche - SGML erlaubt es, daß bestimmte Dokumentabschnitte + SGML erlaubt es, dass 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 + Ein SGML-Prozessor muss 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ß + Parser auf dieses Inhaltsmodell, wird er annehmen, dass sich im zugehörigen Dokumentenbereich nur gewöhnliche Zeichen befinden. Das - bedeutet, daß < und & ihre besondere Bedeutung + bedeutet, dass < 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 + ausgehen, dass 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 < und jedes & durch ein & 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 + muss bedacht werden, dass 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 + dass das SGML in diesen Bereichen gültig ist, + muss 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 < und & 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 + feststellen, dass 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 + fest, dass der Inhalt des betreffenden Abschnittes mitverarbeitet wird. Demgegenüber bestimmt - IGNORE, daß er ignoriert wird, - daß heißt, daß er bei der Verarbeitung + IGNORE, dass er ignoriert wird, + dass heißt, dass 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 + produziert werden, muss 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ß + Bei der Produktion der gedruckten Variante muss 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> Dieser Absatz <![ CDATA [beinhaltet viele < Zeichen (< < < < <). Weshalb es einfacher ist, ihn als CDATA Bereich auszuweisen. ]> <![ IGNORE [ Dieser Absatz wird NICHT in der Ausgabe enthalten sein. ]]> <![ [ Dieser Absatz wird in Abhängigkeit von %text.ausgabe mitausgegeben. ]]> </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. + von sgmlnorm 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 + text.ausgabe so, dass 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. + Verarbeiten Sie dann die Datei erneut mit + sgmlnorm und vergleichen die Ausgabe mit + der vom ersten sgmlnorm 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/the-website/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/the-website/chapter.sgml index de432c41b3..e4617ed726 100644 --- a/de_DE.ISO8859-1/books/fdp-primer/the-website/chapter.sgml +++ b/de_DE.ISO8859-1/books/fdp-primer/the-website/chapter.sgml @@ -1,51 +1,247 @@ - # Die Webseite + + + + Johann + Kois + Übersetzt von + + + - Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie - bitte das - Original in englischer Sprache. + Die Webseite + + + Vorbereitung + + Sie benötigen mindestens 200 MB freien Speicherplatz. + Dieser Platz wird von den SGML-Werkzeugen, den nötigen Teilen + des CVS-Baums, für temporären Speicher zum Bau der Seiten + sowie für die Installation der Webseiten benötigt. Sind + die SGML-Werkzeuge und der CVS-Baum bereits installiert, reichen + etwa 100 MB an freiem Speicherplatz aus. + + + Stellen Sie sicher, dass Ihre Dokumentationsports aktuell + sind. Wenn Sie sich nicht sicher sind, entfernen Sie die alten + Ports mit &man.pkg.delete.1;, bevor Sie die neue Version + installieren. Derzeit wird unter anderem jade-1.2 vorausgesetzt. + Haben Sie beispielsweise jade-1.1 installiert, deinstallieren Sie + es mit: + + &prompt.root; pkg_delete jade-1.1 + + + Legen Sie ein CVS-Repository an. Sie benötigen die + Verzeichnisse www, doc sowie ports des CVS-Baums (und + natürlich CVSROOT). Lesen Sie bitte den Abschnitt + + Synchronisation der Quellen des Handbuchs, der die + Spiegelung eines CVS-Baumes oder eines Teilbaumes + beschreibt. + + Die unbedingt nötigen cvsup-Sammlungen sind + www, doc-all, + cvs-base, sowie + ports-base. + + Diese Sammlungen benötigen etwa 105 MB an freiem + Speicherplatz. + + Der komplette CVS-Baum - inklusive src, + doc, www, und + ports - umfasst derzeit etwa 940 MB. + + + + Die Internetseiten neu bauen + + + + Wechseln Sie in das Verzeichnis, in dem Sie die Webseiten + bauen wollen. Sie benötigen dazu mindestens 60 MB + freien Speicherplatz. + + &prompt.root; mkdir /var/tmp/webbuild +&prompt.root; cd /var/tmp/webbuild + + + + Checken Sie die SGML-Dateien aus dem CVS-Baum aus. + + &prompt.root; cvs -R co www doc + + + + Wechseln Sie ins Verzeichnis www und + führen Sie &man.make.1; links + aus, um die nötigen symbolischen Links zu erzeugen. + + &prompt.root; cd www +&prompt.root; make links + + + + Wechseln Sie ins Verzeichnis en und + führen Sie &man.make.1; all aus, + um die Webseiten zu erzeugen. + + &prompt.root; cd en +&prompt.root; make all + + + + + + Installieren der Webseiten auf Ihrem Server + + + + Wechseln Sie wieder in das Verzeichnis + en, falls Sie dieses inzwischen + verlassen haben. + + &prompt.root; cd path/www/en + + + + Führen Sie &man.make.1; install + aus, und setzen Sie die Variable DESTDIR auf + das Verzeichnis, in das Sie die Webseiten installieren + wollen. + + &prompt.root; make DESTDIR=/usr/local/www install + + + + Wenn Sie die Webseiten bereits früher in dieses + Verzeichnis installiert haben, wurden während der + Installation keine veralteten Seiten entfernt. Wenn + Sie die Webseiten beispielsweise täglich neu bauen + und installieren, findet und entfernt der folgende Befehl + alle Dateien, die in den letzten drei Tagen nicht aktualisiert + wurden: + + &prompt.root; find /usr/local/www -ctime 3 -print0 | xargs -0 rm + + + + + + Umgebungsvariablen + + + + CVSROOT + + + Der Ort des CVS-Baums. Unbedingt notwendig. + + &prompt.root; CVSROOT=/home/ncvs; export CVSROOT + + + + + ENGLISH_ONLY + + + Ist diese Variable gesetzt und nicht leer, bauen und + installieren die Makefiles ausschließlich die + englischen Dokumente. Sämtliche Übersetzungen + werden dabei ignoriert. Dazu ein Beispiel: + + &prompt.root; make ENGLISH_ONLY=YES all install + + Wenn Sie die Variable ENGLISH_ONLY + deaktivieren und alle Webseiten inklusive aller + Übersetzungen bauen wollen, setzen Sie die Variable + ENGLISH_ONLY auf einen leeren Wert: + + &prompt.root; make ENGLISH_ONLY="" all install clean + + + + + WEB_ONLY + + + Ist diese Variable gesetzt und nicht leer, bauen und + installieren die Makefiles nur die HTML-Seiten des + www-Verzeichnisses. Alle Dokumente des doc-Verzeichnisses + (Handbuch, FAQ, Artikel) werden dabei ignoriert: + + &prompt.root; make WEB_ONLY=YES all install + + + + + NOPORTSCVS + + + Ist diese Variable gesetzt, checken die Makefiles keine + Dateien aus dem Ports-CVS-Repository aus. Stattdessen werden + die Dateien aus dem Verzeichnis + /usr/ports (oder aus dem Verzeichnis, + auf das die Variable PORTSBASE zeigt) + verwendet. + + + + + Bei CVSROOT handelt es sich um eine + Umgebungsvariable. Sie muss auf der Kommandozeile oder in der + Konfigurationsdatei ~/.profile gesetzt + werden. + + WEB_ONLY, ENGLISH_ONLY + und NOPORTSCVS sind Variablen für Makefiles. + Diese werden entweder in /etc/make.conf, in + Makefile.inc oder als Umgebungsvariablen auf + der Kommandozeile oder in Ihrer Konfigurationsdatei gesetzt. + diff --git a/de_DE.ISO8859-1/books/fdp-primer/translations/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/translations/chapter.sgml index 9a407a1a2f..7d3360d89c 100644 --- a/de_DE.ISO8859-1/books/fdp-primer/translations/chapter.sgml +++ b/de_DE.ISO8859-1/books/fdp-primer/translations/chapter.sgml @@ -1,51 +1,516 @@ - # Übersetzungen in andere Sprachen + + + + Johann + Kois + Übersetzt von + + + - Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie - bitte das - Original in englischer Sprache. + Übersetzungen + + Dieses Kapitel enthält die FAQ für die Übersetzung + der FreeBSD Dokumentation (FAQ, Handbuch, Artikel, Manualpages und + sonstige Dokumente) in andere Sprachen. + + Es beruht sehr stark auf den + Übersetzungs-FAQ des FreeBSD German Documentation Projects, die + ursprünglich von Frank Gründer + elwood@mc5sys.in-berlin.de geschrieben und danach von + Bernd Warken bwarken@mayn.de ins Englische + übersetzt wurden. + + Diese FAQ wird vom &a.doceng; gepflegt. + + + + + Warum eine FAQ? + + + + Es melden sich immer mehr Leute auf der Mailingliste + freebsd-doc, die Teile der FreeBSD Dokumentation in andere + Sprachen übersetzen wollen. Diese FAQ soll die + am häufigsten gestellten Fragen beantworten, damit + möglichst rasch mit der Übersetzung begonnen + werden kann. + + + + + + Was bedeuten die Abkürzungen i18n + und l10n? + + + + i18n steht für + internationalization + (Internationalisierung), l10n für + localization (Lokalisierung). + Es handelt sich dabei um besser handhabbare Abkürzungen + dieser Begriffe. + + i18n kann als i, gefolgt + von 18 Buchstaben, gefolgt von einem n, gelesen + werden. Analog steht l10n für + l, gefolgt von 10 Buchstaben, gefolgt von einem + n. + + + + + + Gibt es eigene Mailinglisten für Übersetzer? + + + + Ja. Die verschiedenen Übersetzergruppen haben jeweils + eigene Mailinglisten. Genauere Informationen finden Sie in der + + Liste der Übersetzungsprojekte. Diese Liste + enthält die Mailinglisten und Internetseiten, die von den + einzelnen Übersetzungsprojekten betrieben werden. + + + + + + Werden noch Übersetzer benötigt? + + + + Ja. Je mehr Leute an der Übersetzung arbeiten, desto + schneller wird diese fertig, und umso schneller sind + Änderungen im englischen Original auch in den + übersetzten Dokumenten vorhanden. + + Sie müsssen kein professioneller Dolmetscher sein, um + dabei zu helfen. + + + + + + Welche Sprachen muss ich dafür kennen/können? + + + + Idealerweise haben Sie gute Kenntnisse in geschriebenem + Englisch, außerdem sollten Sie natürlich fit in + der Sprache sein, in die Sie übersetzen wollen. + + Englisch ist allerdings nicht unbedingt nötig. Sie + könnten beispielsweise auch die FAQ vom Spanischen ins + Ungarische übersetzen. + + + + + + Welche Software wird benötigt? + + + + Es ist sehr empfehlenswert, eine lokale Kopie des FreeBSD + CVS-Repository (als Minimum den Dokumentationsteil) anzulegen, + entweder mit CTM oder mit + CVSup. Das Kapitel Das + Neueste und Beste des Handbuchs beschreibt die + Nutzung dieser Programme. + + Sie sollten außerdem mit + CVS vertraut sein. Damit ist es + möglich, festzustellen, was sich zwischen einzelnen + Versionen eines Dokuments geändert hat. + + [XXX Aufgabe -- Ein Tutorial schreiben, das die Verwendung + von CVSup beschreibt, um die Dokumentation herunterzuladen, + auszuchecken und festzustellen, was sich zwischen zwei + Versionen geändert hat.] + + + + + + Wie finde ich heraus, ob noch jemand Teile der + Dokumentation in die gleiche Sprache übersetzt? + + + + Die + Übersetzungsseite des Documentation Projects + listet alle Übersetzungs-Teams auf, die derzeit aktiv + sind. Arbeitet bereits jemand an der Übersetzung in + Ihre Sprache, so kontaktieren Sie dieses Team, damit + Dokumente nicht unnötigerweise mehrfach übersetzt + werden. + + Wenn Ihre Sprache nicht aufgeführt ist, senden Sie + bitte eine E-Mail an das &a.doc;. Vielleicht denkt ja jemand + über eine Übersetzung nach, hat sich aber noch nicht + dafür entschieden. + + + + + + Niemand ü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 dafür nötige + Zeit zur Verfügung haben. Da Sie als Einziger an der + Übersetzung in Ihre Sprache arbeiten, sind Sie dafür + verantwortlich, Ihre Arbeit zu verö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 Übersetzung der Dokumentation arbeiten, damit die + Internetseiten aktualisiert werden können. + + Gibt es in Ihrem Land einen FreeBSD-Spiegelserver, so + sollten Sie den dafür Zuständigen kontaktieren und + nachfragen, ob er Ihnen Speicherplatz oder E-Mailadressen + für Ihr Projekt zur Verfügung stellen würde. + + Danach wählen Sie ein Dokument aus und beginnen + mit der Übersetzung. Am besten beginnen Sie mit kleineren + Dateien, beispielsweise den FAQ oder einem der Artikel. + + + + + + Ich habe ein Dokument übersetzt. Wo soll ich es + hinschicken? + + + + Das kommt darauf an. Wenn Sie bereits in einem + Ü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 + Übersetzung in eine Sprache arbeitet, oder wenn Sie + für ein Übersetzungsprojekt verantwortlich sind, + und Ihre Aktualisierungen an das FreeBSD Project + übermitteln wollen, sollten Sie Ihre Übersetzungen + dorthin senden (lesen Sie dazu auch die nächste + Frage). + + + + + + Ich arbeite als einziger an der Übersetzung in diese + Sprache, wie versende ich meine Übersetzungen? + + oder + + Wir sind ein Übersetzer-Team, und wollen Dokumente + versenden, die unsere Mitglieder übersetzt haben? + + + + Stellen Sie zuerst sicher, dass Ihre Übersetzungen + korrekt organisiert sind. Sie sollte sich also im + existierenden Dokumentationsbaum befinden, und ohne Fehler + bauen lassen. + + Zurzeit wird die FreeBSD Dokumentation unterhalb des + Verzeichnisses doc/ gespeichert. Die + direkten Unterverzeichnisse werden entsprechend der + Sprachkodierung benannt, in der sie geschrieben sind. Diese + Kodierung nach ISO639 finden Sie auf einem FreeBSD-System + unter /usr/share/misc/iso639, + vorausgesetzt, das System wurde nach dem 20. Januar 1999 + gebaut. + + Wenn in Ihrer Sprache mehrere Kodierungen (wie dies etwa + für Chinesisch der Fall ist) vorhanden sind, existiert + für jede Kodierung ein eigenes Unterverzeichnis. + + Zuletzt existieren auch noch Verzeichnisse für die + einzelnen Dokumente. + + Die Verzeichnishierarchie für eine hypothetische + schwedische Übersetzung könnte etwa so + aussehen: + + doc/ + sv_SE.ISO8859-1/ + Makefile + books/ + faq/ + Makefile + book.sgml + + Bei sv_SE.ISO8859-1 handelt es sich um + den Namen der Übersetzung in der + lang.encoding + Form. Beachten Sie auch, dass zum Bauen der Dokumentation + zwei Makefiles notwendig sind. + + Komprimieren Sie Ihre Übersetzungen mit &man.tar.1; + und &man.gzip.1; und senden Sie sie an das FreeBSD + Project. + + &prompt.user; cd doc +&prompt.user; tar cf swedish-docs.tar sv +&prompt.user; 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 Verfügung stellt), + können Sie auch eine E-Mail an das &a.doceng; schicken, um + abzuklären, ob Sie die Datei auch als E-Mail schicken + können. + + In beiden Fällen sollten Sie mit &man.send-pr.1; + einen Bericht über den Versand der Dokumentation + erstellen. Es ist sehr hilfreich, wenn Sie Ihre + Übersetzung vorher korrekturlesen lassen und + überprü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 &a.doceng;) überprüfen, + ob sich Ihre Übersetzungen problemlos bauen lassen. Dabei + wird besonders auf folgende Punkte geachtet: + + + + Verwenden alle Dateien RCS-Strings (wie "ID")? + + + + Arbeitet make all im Verzeichnis + sv_SE.ISO8859-1 korrekt? + + + + 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 Übersetzung + so rasch als möglich committed. + + + + + + Kann ich landes- oder sprachspezifische Informationen + in meine Übersetzung aufnehmen? + + + + Wir bitten Sie, dies nicht zu tun. + + Nehmen wir an, dass Sie das Handbuch ins Koreanische + übersetzen und einen Abschnitt mit + Hä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 während eines Aufenthalts in Korea eine + FreeBSD-Kopie kaufen möchte. Außerdem wird dadurch + die weltweite Präsenz von FreeBSD verdeutlicht, was + natürlich ebenfalls von Vorteil ist. + + Wenn Sie also länderspezifische Informationen + ergänzen wollen, sollten Sie dies zuerst in der englischen + Version (mittels &man.send-pr.1;) tun, und die Änderung + anschließend in Ihre Sprache übersetzen. + + Vielen Dank. + + + + + + Wie lassen sich sprachspezifische Zeichen darstellen? + + + + Nicht-ASCII-Zeichen innerhalb der Dokumentation werden + durch SGML-Entities dargestellt. + + Diese bestehen aus: Kaufmä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 + + Darstellung + + Beschreibung + + + é + é + Kleines e mit (akutem) Akzent + + + + É + É + Großes E mit (akutem) Akzent + + + + ü + ü + Kleines Umlaut-u + + + + Nachdem Sie den iso8879-Port installiert haben, ist die + vollständige Liste unter + /usr/local/share/sgml/iso8879 + vorhanden. + + + + + + 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 übersetzen, die diese + Unterscheidung trifft, verwenden Sie die Form, die auch in + den anderen technischen Dokumentationen dieser Sprache + verwendet wird. Für deutsche Versionen ist dies die + dritte Person Plural (Sie). + + + + + + Muss ich zusätzliche Informationen in meine + Übersetzungen einbauen? + + + + Ja. + + Der Header der englischen Version jedes Textes sieht in + etwa so aus: + +  + + Das exakte Aussehen kann unterschiedlich sein, die Zeile + mit $FreeBSD$ sowie der Ausdruck The + FreeBSD Documentation Project sind allerdings immer + enthalten. Beachten Sie, dass die Zeile mit $FreeBSD + von CVS automatisch expandiert wird, daher sollte an dieser + Stelle in Ihren neuen Dokumenten nur + $FreeBSD$ stehen. + + Ihre übersetzten Dokumente sollten eine eigene + $FreeBSD$-Zeile enthalten. Zusätzlich + sollten Sie die Zeile mit The FreeBSD Documentation + Project in The FreeBSD + Ihre-Sprache Documentation + Project ändern. + + Außerdem sollten Sie eine weitere Zeile + einfügen, die festlegt, auf welcher Version des englischen + Originals Ihre Übersetzung basiert. + + Die spanische Version dieser Datei könnte etwa so + beginnen: + +  + + + 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 index bf2df3d219..d3da4894db 100644 --- a/de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml +++ b/de_DE.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml @@ -1,51 +1,526 @@ - # Der Schreibstil + + + + Johann + Kois + Übersetzt von + + + - Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie - bitte - das Original in englischer Sprache. + Der Schreibstil + + Damit von verschiedenen Autoren geschriebene Dokumente + zueinander konsistent bleiben, gibt es einige Richtlinien, denen + Autoren bei der Erstellung ihrer Dokumente folgen müssen. + + + + Verwendung von amerikanischem Englisch + + + Es gibt mehrere englische Varianten und damit verbunden + verschiedene Schreibweisen fü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. + + + + + Vermeiden von Zusammenziehungen + + + Verwenden Sie keine Zusammenziehungen, sondern schreiben + Sie die Phrase immer aus. Die Schreibweise + Don't use contractions. wäre also nicht + korrekt. + + Die Vermeidung von Zusammenziehungen sorgt für einen + etwas formelleren Ton, ist präziser und erleichtert die + Arbeit der Übersetzer. + + + + + Nutzung von Kommas bei Aufzählungen + + + Bei einer Aufzä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 für die Ausdrücke + der Befehl, die Datei, und + man command. + + Die folgenden zwei Beispiele veranschaulichen dies + für Befehle. Bevorzugt wird die Schreibweise des + zweiten Beispiels. + + + Verwenden Sie den Befehl cvsup, um + Ihre Quellen zu aktualisieren. + + + + Verwenden Sie cvsup, um Ihre Quellen + zu aktualisieren. + + + Analoges gilt für Dateinamen, wobei wiederum die + zweite Schreibweise bevorzugt wird. + + + … in der Datei + /etc/rc.local… + + + + … in + /etc/rc.local… + + + Auch fü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 &man.csh.1;. + + + + + Zwei Leerzeichen am Satzende + + + Verwenden Sie immer zwei Leerzeichen am Ende eines Satzes. + Dadurch erhöht sich die Lesbarkeit des Textes und die + Nutzung von Werkzeugen wie Emacs + wird vereinfacht. + + Nun könnte man behaupten, dass ein Punkt vor einem + Großbuchstaben das Satzende markiert. Vor allem bei + Namen, beispielsweise bei Jordan K. Hubbard, + ist dies allerdings nicht der Fall. Wir haben hier ein + großes H, gefolgt von einem Punkt + und einem Leerzeichen. Dennoch handelt es sich nicht um + den Anfang eines neuen Satzes. + + + + + Eine ausführliche Beschreibung des korrekten Schreibstils + finden Sie im Buch Elements + of Style von William Strunk. + + + Anleitungen für einen korrekten Schreibstil + + Damit die Quellen der Dokumentation selbst dann konsistent + bleiben, wenn viele Leute daran arbeiten, folgen Sie bitte den + folgenden Konventionen. + + + Groß- und Kleinschreibung + + Tags werden in Kleinbuchstaben geschrieben, Sie schreiben + also <para>, nicht + <PARA>. + + Text im SGML-Kontext wird hingegen in Großbuchstaben + geschrieben. Man schreibt also + <!ENTITY…> und + <!DOCTYPE…>, + nicht + <!entity…> und + <!doctype…>. + + + + Abkürzungen (Akronyme) + + Abkürzungen sollten bei ihrer ersten Verwendung immer + ausgeschrieben werden. Man schreibt also beispielsweise + "Network Time Protocol + (NTP)." Nachdem + die Abkürzung definiert wurde, sollte hingegen nur noch die + Abkürzung verwendet werden, es sei denn, die Verwendung des + gesamten Begriffes macht im jeweiligen Kontext mehr Sinn. + Im Normalfall werden Akronyme in jedem Buch nur einmal definiert. + Es ist allerdings auch möglich, sie für jedes Kapitel + erneut zu definieren. + + Die drei ersten Vorkommen der Abkürzung sollten in + <acronym>-Tags eingeschlossen werden. Zusätzlich + wird ein role-Attribut mit dem + vollständigen Begriff definiert. Dadurch kann ein Link + zu einem Glossar erzeugt werden. Außerdem wird der + komplette Begriff angezeigt, wenn man den Mauscursor über + die Abkürzung bewegt. + + + + Einrückung + + Die erste Zeile jeder Datei hat die Einrückung 0, und + zwar unabhängig von der Einrückung + der Datei, in der sie enthalten ist. + + Öffnende Tags erhöhen die Einrückung um zwei + Leerzeichen. Schließende 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, führende Leerzeichen sind hier also + nicht erlaubt. Vermeiden Sie außerdem Leerzeichen am + Zeilenende. Der Inhalt von Elementen wird um zwei Leerzeichen + eingerückt, wenn er sich über mehr als eine Zeile + erstreckt. + + Der Quellcode dieses Abschnitts sieht daher in etwa so + aus: + + + ... + + + ... + + + Einrückung + + Die erste Zeile jeder Datei hat die Einrückung 0, und + zwar unabhängig von der Einrückung + der Datei, in der sie enthalten ist. + + ... + + +]]> + + 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 spaces + 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 + + + + + Die korrekte Schreibweise von Tags + + + Einrücken von Tags + + Tags, die die gleiche Einrückung aufweisen wie das + vorangegangene Tag, sollten durch eine Leerzeile getrennt + werden, Tags mit unterschiedlicher Einrückung hingegen + nicht: + + + + + NIS + + October 1999 + + + ... + ... + ... + + + + + ... + + ... + + + + ... + + ... + +]]> + + + + + Gliederung von Tags + + Tags wie zum Beispiel itemizedlist, die + immer weitere Tags einschließen und selbst keine Zeichen + enthalten, befinden sich immer in einer eigenen Zeile. + + Tags wie para und + term kö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 + führen. + + Wenn auf ein Start-Tag, das keine Zeichen enthalten kann, + unmittelbar ein Tag folgt, das andere Tags einschließen + muss, um Zeichen darzustellen, befinden sich diese Tags auf + verschiedenen Zeilen. Das zweite Tag wird dabei + entsprechend eingerü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. + + + + + Markup-Änderungen (<foreignphrase>white space + changes</foreignphrase>) + + Wenn Sie Änderungen committen, committen Sie + niemals Inhalts- und Formatierungsänderungen zur gleichen + Zeit. + + Nur auf diese Weise können die Übersetzungs-Teams + sofort erkennen, welche Änderungen durch Ihren Commit + verursacht wurden, ohne darüber nachdenken zu müssen, + ob sich eine Zeile geädert hat, weil Sie den Inhalt + geändert haben, oder weil Sie sie nur umformatiert + haben. + + Nehmen wir an, Sie haben zwei Sätze in einen Absatz + eingefügt. Daher sind zwei Zeilen nun länger als + 80 Zeichen. Zuerst committen Sie Ihre inhaltliche + Änderung inklusive der zu langen Zeilen. Im nächsten + Commit korrigieren Sie den Zeilenumbruch und geben in der + Commit-Mitteilung an, dass es sich nur um Änderung am + Markup handelt (whitespace-only + change), und Übersetzer den Commit daher + ignorieren können. + + + + Vermeiden von fehlerhaften Zeilenumbrüchen + (Nutzung von <foreignphrase>nonbreaking space</foreignphrase>) + + Vermeiden Sie Zeilenumbrüche an Stellen, an denen diese + häßlich aussehen oder es erschweren, einem Satz zu + folgen. Zeilenumbrüche hängen von der Breite des + gewählten Augabemedium ab. Insbesondere bei der Verwendung + von Textbrowsern können schlecht formatierte Absätze + wie der folgende entstehen: + + Data capacity ranges from 40 MB to 15 +GB. Hardware compression … + + Die Nutzung der Entity   + verhindert Zeilenumbrüche zwischen zusammengehörenden + Teilen. Verwenden Sie nonbreaking + spaces daher in den folgenden Fällen: + + + + Zwischen Zahlen und Einheiten: + + + + + Zwischen Programmnamen und Versionsnummern: + + + + + Zwischen mehreren zusammengehörenden Wörtern + (Vorsicht bei Namen, die aus mehr als 3-4 Wörtern + bestehen, wie The FreeBSD Brazilian Portuguese + Documentation Project): + + + + + + + + Häufig verwendete Wörter + + Die folgende Liste enthält einige Beispiele, wie + bestimmte Wörter innerhalb des FreeBSD + Documentation Projects geschrieben werden. Finden Sie ein + gesuchtes Wort hier nicht, sehen Sie bitte in der + Liste häufig verwendeter Wörter von + O'Reilly nach. + + + + 2.2.X + + + + 4.X-STABLE + + + + CDROM + + + + DoS (Denial of Service) + + + + FreeBSD Ports Collection + + + + IPsec + + + + Internet + + + + MHz + + + + Soft Updates + + + + Unix + + + + disk label + + + + email + + + + file system + + + + manual page + + + + mail server + + + + name server + + + + ports collection + + + + web server + + + +