diff options
Diffstat (limited to 'de_DE.ISO8859-1/books/fdp-primer/structure/chapter.sgml')
| -rw-r--r-- | de_DE.ISO8859-1/books/fdp-primer/structure/chapter.sgml | 297 |
1 files changed, 292 insertions, 5 deletions
diff --git a/de_DE.ISO8859-1/books/fdp-primer/structure/chapter.sgml b/de_DE.ISO8859-1/books/fdp-primer/structure/chapter.sgml index bb313ba258..16b25aaeff 100644 --- a/de_DE.ISO8859-1/books/fdp-primer/structure/chapter.sgml +++ b/de_DE.ISO8859-1/books/fdp-primer/structure/chapter.sgml @@ -28,15 +28,302 @@ POSSIBILITY OF SUCH DAMAGE. $FreeBSD$ - $FreeBSDde: de-docproj/books/fdp-primer/structure/chapter.sgml,v 1.4 2004/08/30 22:39:59 mheinen Exp $ + $FreeBSDde: de-docproj/books/fdp-primer/structure/chapter.sgml,v 1.5 2005/09/22 17:50:36 jkois Exp $ + + basiert auf: 1.17 --> <chapter id="structure"> - <title># Verzeichnisstruktur unter <filename>doc/</filename></title> + <chapterinfo> + <authorgroup> + <author> + <firstname>Johann</firstname> + <surname>Kois</surname> + <contrib>Übersetzt von </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>Verzeichnisstruktur unter <filename>doc/</filename></title> + + <para>Der <filename>doc/</filename>-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</para> + + <orderedlist> + <listitem> + <para>die automatische Konvertierung der Dokumente in andere + Formate einfach zu gestalten,</para> + </listitem> + + <listitem> + <para>die Konsistenz zwischen den verschiedenen auf diese Weise + organisierten Dokumenten sicherzustellen, was die parallele + Bearbeitung verschiedener Dokumente vereinfacht, sowie</para> + </listitem> + + <listitem> + <para>die Entscheidung, wo neue Dokumente innerhalb des Baumes + platziert werden sollen, zu erleichtern.</para> + </listitem> + </orderedlist> + + <para>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.</para> + + <sect1 id="structure-top"> + <title><filename>doc/</filename> als höchste Ebene</title> + + <para>Unterhalb von <filename>doc/</filename> existieren zwei + Arten von Verzeichnissen, die jeweils über spezifische + Dateinamen und eine spezifische Bedeutung verfügen.</para> + + <segmentedlist> + <segtitle>Verzeichnis</segtitle> + + <segtitle>Bedeutung</segtitle> + + <seglistitem> + <seg><filename>share/</filename></seg> + + <seg>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 + <filename>share/mk</filename> 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 + <filename>share/sgml</filename> befinden.</seg> + </seglistitem> + + <seglistitem> + <seg><filename><replaceable>Sprache</replaceable>.<replaceable>Kodierung</replaceable>/</filename></seg> + + <seg>Für jede verfügbare Sprache und Kodierung + existiert ein eigenes Unterverzeichnis. Beispiele dafür + sind <filename>en_US.ISO8859-1/</filename> oder + <filename>zh_TW.Big5/</filename>. 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.</seg> + </seglistitem> + </segmentedlist> + </sect1> + + <sect1 id="structure-locale"> + <title>Die Verzeichnisse + <filename><replaceable>Sprache</replaceable>.<replaceable>Kodierung</replaceable>/</filename></title> + + <para>Diese Verzeichnisse enthalten die eigentliche Dokumentation. + Auf dieser Ebene erfolgt eine Unterteilung in drei Kategorien, + die durch entsprechende Verzeichnisnamen gekennzeichnet + werden.</para> + + <segmentedlist> + <segtitle>Verzeichnis</segtitle> + + <segtitle>Inhalt</segtitle> + + <seglistitem> + <seg><filename>articles</filename></seg> + + <seg>DocBook-formatierte Artikel (<sgmltag>article</sgmltag>) + oder ähnliche Dokumente. Meist relativ kurz und in + Abschnitte aufgeteilt. Artikel sind in der Regel als ein + einziges, großes HTML-Dokument verfügbar.</seg> + </seglistitem> + + <seglistitem> + <seg><filename>books</filename></seg> + + <seg>DocBook-formatierte Bücher (<sgmltag>book</sgmltag>) + 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 + 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.</seg> + </seglistitem> + + <seglistitem> + <seg><filename>man</filename></seg> + + <seg>Dient für Übersetzungen von Manualpages. Es + enthält ein oder mehrere + <filename>man<replaceable>n</replaceable></filename>-Verzeichnisse, + je nachdem, welche Abschnitte der Manualpages bereits + übersetzt wurden.</seg> + </seglistitem> + </segmentedlist> + + <para>Nicht jedes + <filename><replaceable>Sprache</replaceable>.<replaceable>Kodierung</replaceable></filename>-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.</para> + </sect1> + + <sect1 id="structure-document"> + <title>Dokumentenspezifische Informationen</title> + + <para>Dieser Abschnitt enthält Informationen zu einigen vom + FreeBSD Documentation Project (FDP) verwalteten + Dokumenten.</para> + + <sect2> + <title>Das Handbuch</title> + + <subtitle><filename>books/handbook/</filename></subtitle> + + <para>Das Handbuch wurde unter Verwendung der vom FreeBSD + Project erweiterten DocBook-DTD geschrieben.</para> + + <para>Das Handbuch ist als DocBook-<sgmltag>book</sgmltag> + organisiert. Es besteht aus mehreren Teilen + (<sgmltag>part</sgmltag>s), die wiederum mehrere + Kapitel (<sgmltag>chapter</sgmltag>) enthalten können. + Kapitel sind zusätzlich in Abschnitte + (<sgmltag>sect1</sgmltag>) und Unterabschnitte + (<sgmltag>sect2</sgmltag>, <sgmltag>sect3</sgmltag> und so + weiter) unterteilt.</para> + + <sect3> + <title>Physikalische Organisation</title> + + <para>Das Verzeichnis <filename>handbook</filename> enthält + sowohl weitere Verzeichnisse als auch zahlreiche einzelne + Dateien.</para> + + <note> + <para>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;.</para> + </note> + + <sect4> + <title><filename>Makefile</filename></title> + + <para>Das <filename>Makefile</filename> definiert verschiedene + Variablen zur Konvertierung der SGML-Quellen in andere + Formate. Außerdem listet es die verschiedenen Dateien + auf, aus denen das Handbuch gebaut wird. Zusätzlich + wird die Standard-<filename>doc.project.mk</filename> + inkludiert, die den für die Konvertierung in andere + Formate notwendigen Code bereitstellt.</para> + </sect4> + + <sect4> + <title><filename>book.sgml</filename></title> + + <para>Das Hauptdokument innerhalb des Handbuchs. Neben der + <link linkend="sgml-primer-doctype-declaration"> + DOCTYPE-Deklaration</link> des Handbuchs werden hier auch + die Elemente aufgelistet, die die Struktur des Handbuchs + definieren.</para> + + <para><filename>book.sgml</filename> verwendet <link + linkend="sgml-primer-parameter-entities"> + Parameterentitäten</link>, um Dateien mit der + Endung <filename>.ent</filename> zu laden. Diese + Dateien definieren die <link + linkend="sgml-primer-general-entities">allgemeinen + Entitäten</link>, die innerhalb des Handbuchs + verwendet werden.</para> + </sect4> + + <sect4> + <title><filename><replaceable>Verzeichnis</replaceable>/chapter.sgml</filename></title> + + <para>Jedes Kapitel des Handbuchs wird in einer + <filename>chapter.sgml</filename> genannten Datei + gespeichert. Jedes Verzeichnis erhält den Namen + des <literal>id</literal>-Attributs des + <sgmltag>chapter</sgmltag>-Elements.</para> + + <para>Enthält eine Kapiteldatei beispielsweise die + Einträge</para> + + <programlisting><![ CDATA [ +<chapter id="kernelconfiguration"> +... +</chapter>]]></programlisting> + + <para>so handelt es sich um die Datei + <filename>chapter.sgml</filename> im Verzeichnis + <filename>kernelconfiguration</filename>. Im Allgemeinen + enthält diese Datei das komplette Kapitel.</para> + + <para>Wird die HTML-Version des Handbuchs gebaut, entsteht + dadurch die HTML-Datei + <filename>kernelconfiguration.html</filename>. Der Grund + dafür ist allerdings der Wert des + <literal>id</literal>-Attributs, und nicht der Name des + Verzeichnisses.</para> + + <para>In früheren Versionen des Handbuchs wurden all + diese Dateien im gleichen Verzeichnis wie die Datei + <filename>book.sgml</filename> gespeichert und nach dem + Wert des <literal>id</literal>-Attributs der + <sgmltag>chapter</sgmltag>-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. Es ist sinnvoller, den Text und + die Bilder eines Kapitels in einem gemeinsamen Verzeichnis + zu speichern, statt für alle Dateien des Handbuchs + nur ein gemeinsames Verzeichnis zu verwenden. 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.</para> + + <para>Durch dieses Vorgehen entstanden viele Verzeichnisse, + die jeweils eine <filename>chapter.sgml</filename> enhalten, + beispielsweise <filename>basics/chapter.sgml</filename>, + <filename>introduction/chapter.sgml</filename> oder + <filename>printing/chapter.sgml</filename>.</para> + + <important> + <para>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.</para> + </important> + + <para>Die Datei <filename>chapter.sgml</filename> ist keine + komplette SGML-Datei, da unter anderem die Zeilen mit + der DOCTYPE-Deklaration am Beginn der Datei nicht + vorhanden sind.</para> - <para>Dieser Abschnitt ist noch nicht übersetzt. Lesen Sie - bitte <ulink url="&url.books.fdp-primer.en;/structure.html">das - Original in englischer Sprache</ulink>.</para> + <para>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 <emphasis>komplette</emphasis> Handbuch neu gebaut + werden.</para> + </sect4> + </sect3> + </sect2> + </sect1> </chapter> <!-- |