Index: head/de_DE.ISO8859-1/books/fdp-primer/structure/chapter.xml =================================================================== --- head/de_DE.ISO8859-1/books/fdp-primer/structure/chapter.xml (revision 46799) +++ head/de_DE.ISO8859-1/books/fdp-primer/structure/chapter.xml (revision 46800) @@ -1,321 +1,327 @@ - Verzeichnisstruktur unter <filename>doc/</filename> + Dokumentation-Verzeichnisstruktur JohannKoisÜbersetzt von - + Die Struktur der Dateien und Ordner unterhalb von + doc/ hilft dabei, - Der doc/-Baum ist auf eine besondere - Weise organisiert. Dies gilt analog für die Dokumente, aus - denen der FDP besteht. Das Ziel dieser Organisation ist es, das - Hinzufügen neuer Dokumente zu erleichtern, sowie - die automatische Konvertierung der Dokumente in andere Formate einfach zu gestalten, die Konsistenz zwischen den verschiedenen auf diese Weise organisierten Dokumenten sicherzustellen, was die parallele Bearbeitung verschiedener Dokumente vereinfacht, sowie die Entscheidung, wo neue Dokumente innerhalb des Baumes - platziert werden sollen, zu erleichtern. + platziert werden sollen, leichter zu machen. Zusätzlich wird dadurch dem Umstand Rechnung getragen, dass die Dokumentation in verschiedenen Sprachen und Kodierungen vorhanden sein kann. Es ist von großer Bedeutung, dass die Struktur des Dokumentationsbaumes dabei dennoch einheitlich bleibt. <filename>doc/</filename> als höchste Ebene Unterhalb von doc/ existieren zwei Arten von Verzeichnissen, die jeweils über spezifische Dateinamen und eine spezifische Bedeutung verfügen. - - Verzeichnis + + + + + Verzeichnis + Bedeutung + + - Bedeutung + + + share - - share/ - - Enthält Dateien, die für alle Sprachen und + Enthält Dateien, die für alle Sprachen und Kodierungen der Dokumentation gültig sind. Es enthält weitere Unterverzeichnisse, um diese Informationen zu kategorisieren. So enthält - share/mk beispielsweise die Dateien, + share/mk + beispielsweise die Dateien, die die &man.make.1;-Infrastruktur bilden, während - sich die für die SMGL-Unterstützung nötigen - Dateien (darunter die FreeBSD DocBook DTD) unter - share/xml befinden. - + sich die für die XML-Unterstützung nötigen + Dateien (darunter die FreeBSD DocBook DTD) unter + share/xml befinden. + - - Sprache.Kodierung/ + + lang.encoding - Für jede verfügbare Sprache und Kodierung + Für jede verfügbare Sprache und Kodierung existiert ein eigenes Unterverzeichnis. Beispiele dafür sind en_US.ISO8859-1/ oder - zh_TW.Big5/. Zwar sind diese + zh_TW.UTF-8/. Zwar sind diese Verzeichnisnamen nicht gerade kurz, durch die vollständige Angabe von Sprache und Kodierung werden aber Probleme bei einer eventuellen Erweiterung der Dokumentation (etwa um eine zusätzliche Kodierung für eine bereits vorhandene Sprache) vermieden. Auch eine eventuelle Konvertierung der Dokumentation nach Unicode ist dadurch problemlos - möglich. - - + möglich. + + + + Die Verzeichnisse - <filename>Sprache.Kodierung/</filename> + Sprache.Kodierung/ Diese Verzeichnisse enthalten die eigentliche Dokumentation. Auf dieser Ebene erfolgt eine Unterteilung in drei Kategorien, die durch entsprechende Verzeichnisnamen gekennzeichnet werden. - - Verzeichnis + + + + + Verzeichis + Bedeutung + + - Inhalt + + + articles - - articles - - DocBook-formatierte Artikel (article) + DocBook-formatierte Artikel (article) oder ähnliche Dokumente. Meist relativ kurz und in Abschnitte aufgeteilt. Artikel sind in der Regel als ein - einziges, großes HTML-Dokument verfügbar. - + einziges, großes XHTML-Dokument verfügbar. + - - books + + books - DocBook-formatierte Bücher (book) + DocBook-formatierte Bücher (book) oder ähnliche Dokumente. Umfangreiche Dokumente, die in Kapitel aufgeteilt werden. Sind in der Regel sowohl - als eine einzige, große HTML-Datei (für Personen + als eine einzige, große XHTML-Datei (für Personen mit einer schnellen Internetanbindung oder für einen einfachen Druck über ein Browser) oder als eine Sammlung von vielen kleinen, miteinander verlinkten Dateien - verfügbar. - + verfügbar. + - - man + + man - Dient für Übersetzungen von Manualpages. Es - enthält ein oder mehrere - mann-Verzeichnisse, + Dient für Übersetzungen von Manualpages. Es + enthält ein oder mehrere mann-Verzeichnisse, je nachdem, welche Abschnitte der Manualpages bereits - übersetzt wurden. - - + übersetzt wurden. + + + + - Nicht jedes - Sprache.Kodierung-Verzeichnis + Nicht jedes Sprache.Kodierung-Verzeichnis enthält all diese Unterverzeichnisse. Ob ein Verzeichnis vorhanden ist, hängt vielmehr davon ab, ob bereits ein entsprechender Teil der Dokumentation übersetzt wurde. Dokumentenspezifische Informationen Dieser Abschnitt enthält Informationen zu einigen vom FreeBSD Documentation Project (FDP) verwalteten Dokumenten. Das Handbuch books/handbook/ - Das Handbuch wurde unter Verwendung der vom FreeBSD - Project erweiterten DocBook-DTD geschrieben. + Das Handbuch wurde unter Verwendung von + DocBook XML (und der vom FreeBSD + Project erweiterten XML DocBook-DTD) + geschrieben. Das Handbuch ist als DocBook-book organisiert. Es besteht aus mehreren Teilen (parts), die wiederum mehrere Kapitel (chapter) enthalten können. Kapitel sind zusätzlich in Abschnitte (sect1) und Unterabschnitte (sect2, sect3 und so weiter) unterteilt. Physikalische Organisation Das Verzeichnis handbook enthält sowohl weitere Verzeichnisse als auch zahlreiche einzelne Dateien. Die Organisation des Handbuchs hat sich im Laufe der Zeit geändert, daher könnten die Informationen in diesem Abschnitt eventuell nicht mehr dem akutellen Stand entsprechen. Haben Sie Fragen zur Organisation des Handbuchs, so wenden Sie sich bitte an das &a.doc;. <filename>Makefile</filename> Das Makefile definiert verschiedene - Variablen zur Konvertierung der XML-Quellen in andere + Variablen zur Konvertierung derXML-Quellen in andere Formate. Außerdem listet es die verschiedenen Dateien auf, aus denen das Handbuch gebaut wird. Zusätzlich wird die Standard-doc.project.mk inkludiert, die den für die Konvertierung in andere Formate notwendigen Code bereitstellt. <filename>book.xml</filename> Das Hauptdokument innerhalb des Handbuchs. Neben der - - DOCTYPE-Deklaration des Handbuchs werden hier auch + DOCTYPE-Deklaration + des Handbuchs werden hier auch die Elemente aufgelistet, die die Struktur des Handbuchs definieren. book.xml verwendet Parameterentitäten, um Dateien mit der Endung .ent zu laden. Diese Dateien definieren die allgemeinen Entitäten, die innerhalb des Handbuchs verwendet werden. - <filename>Verzeichnis/chapter.xml</filename> + <filename + role="directory"><replaceable>Verzeichnis</replaceable>/chapter.xml</filename> Jedes Kapitel des Handbuchs wird in einer chapter.xml genannten Datei gespeichert. Jedes Verzeichnis erhält den Namen des id-Attributs des chapter-Elements. Enthält eine Kapiteldatei beispielsweise die Einträge - + chapter id="kernelconfig" ... -]]> +chapter so handelt es sich um die Datei chapter.xml im Verzeichnis kernelconfig. Im Allgemeinen enthält diese Datei das komplette Kapitel. - Wird die XHTML-Version des Handbuchs gebaut, entsteht - dadurch + Wird die XHTML-Version des Handbuchs + gebaut, entsteht dadurch kernelconfig.html. Der Grund dafür ist allerdings der Wert des id-Attributs, und nicht der Name des Verzeichnisses. In früheren Versionen des Handbuchs wurden all diese Dateien im gleichen Verzeichnis wie die Datei book.xml gespeichert und nach dem Wert des id-Attributs der chapter-Elemente benannt. Durch die Verwendung von eigenen Verzeichnissen für die verschiedenen Kapitel wurde das Handbuch für künftige Erweiterungen vorbereitet. Beispielsweise wurde es dadurch möglich, Bilder in die einzelnen Kapitel aufzunehmen. Die Bilder für das Handbuch werden zentral im Verzeichnis share/images/books/handbook gespeichert. Existiert eine lokalisierte Version eines - Bildes, wird diese hingegen gemeinsam mit dem XML-Quellcode + Bildes, wird diese hingegen gemeinsam mit dem + XML-Quellcode im gleichen Verzeichnis gespeichert. Ein Vorteil dieser Methode ist beispielsweise die Vermeidung von Namenskollisionen. Außerdem ist es übersichtlicher, mit mehreren Verzeichnissen zu arbeiten, die jeweils nur einige Dateien enthalten, als mit einem einzigen Verzeichnis, das eine Vielzahl von Dateien enthält. Durch dieses Vorgehen entstanden viele Verzeichnisse, die jeweils eine chapter.xml enhalten, beispielsweise basics/chapter.xml, introduction/chapter.xml oder printing/chapter.xml. - Im Normalfall sollte ein Umstrukturierung des - Handbuchs nicht dazu führen, dass dafür - Dateien umbenannt werden müssen (es sei denn, - einzelne Kapitel werden neu aufgenommen oder - entfernt). Kapitel und Verzeichnisse sollten daher - nicht nach ihrer Reihenfolge innerhalb des Handbuchs - benannt werden, da sich diese Reihenfolge bei einer - Umstrukturierung des Handbuchs ändern - könnte. + Benennen Sie Kapitel und Verzeichnisse nicht nach + Ihrer Reihenfolge innerhalb des Handbuchs. Dann führt + eine Umstrukturierung des Handbuchs im Normalfall nicht + dazu, dass dafür Dateien umbenannt werden müssen (es sei + denn, einzelne Kapitel werden neu aufgenommen oder + entfernt). Die Datei chapter.xml ist keine - komplette XML-Datei, da unter anderem die Zeilen mit - der DOCTYPE-Deklaration am Beginn der Datei nicht - vorhanden sind. - - Durch diesen Umstand ist es nicht möglich, - einzelne Dateien direkt nach HTML, RTF, PS oder ein - anderes Format zu konvertieren. Vielmehr muss dazu - das komplette Handbuch neu gebaut - werden. + komplette XML-Datei. Dies bedeutet, + dass sie nicht alleine gebaut werden kann, sondern nur + als Teil des Handbuchs.