<?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>