329 lines
12 KiB
XML
329 lines
12 KiB
XML
<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
|
|
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
|
|
|
|
Redistribution and use in source (SGML DocBook) and 'compiled' forms
|
|
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
|
|
modification, are permitted provided that the following conditions
|
|
are met:
|
|
|
|
1. Redistributions of source code (SGML DocBook) must retain the above
|
|
copyright notice, this list of conditions and the following
|
|
disclaimer as the first lines of this file unmodified.
|
|
|
|
2. Redistributions in compiled form (transformed to other DTDs,
|
|
converted to PDF, PostScript, RTF and other formats) must reproduce
|
|
the above copyright notice, this list of conditions and the
|
|
following disclaimer in the documentation and/or other materials
|
|
provided with the distribution.
|
|
|
|
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.
|
|
|
|
$FreeBSD$
|
|
$FreeBSDde$
|
|
basiert auf: r38868
|
|
-->
|
|
|
|
<chapter id="structure">
|
|
<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="kernelconfig">
|
|
...
|
|
</chapter>]]></programlisting>
|
|
|
|
<para>so handelt es sich um die Datei
|
|
<filename>chapter.sgml</filename> im Verzeichnis
|
|
<filename>kernelconfig</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>kernelconfig.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. Die Bilder für das Handbuch
|
|
werden zentral im Verzeichnis <filename
|
|
class="directory">share/images/books/handbook</filename>
|
|
gespeichert. Existiert eine lokalisierte Version eines
|
|
Bildes, wird diese hingegen gemeinsam mit dem SGML-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.</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>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>
|