doc/de_DE.ISO8859-1/books/fdp-primer/structure/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- 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: r46365
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="structure">
  <info><title>Dokumentation-Verzeichnisstruktur</title>
    <authorgroup>
      <author><personname><firstname>Johann</firstname><surname>Kois</surname></personname><contrib>Übersetzt von </contrib></author>
    </authorgroup>
  </info>

 <para>Die Struktur der Dateien und Ordner unterhalb von
  <filename>doc/</filename> hilft dabei,</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, leichter zu machen.</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 xml: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>

    <informaltable pgwide="1" frame="none">
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Verzeichnis</entry>
	    <entry>Bedeutung</entry>
	  </row>
	</thead>

	<tbody>
	  <row>
	    <entry valign="top"><filename>share</filename></entry>

	<entry>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 class="directory">share/mk</filename>
	  beispielsweise die Dateien,
	  die die &man.make.1;-Infrastruktur bilden, während
	  sich die für die <acronym>XML</acronym>-Unterstützung nötigen
	  Dateien (darunter die FreeBSD DocBook  <acronym>DTD</acronym>) unter
	  <filename>share/xml</filename> befinden.</entry>
	  </row>

	  <row>
	    <entry valign="top"><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>

	<entry>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.UTF-8/</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.</entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>
  </sect1>

  <sect1 xml: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>

    <informaltable pgwide="1" frame="none">
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Verzeichis</entry>
	    <entry>Bedeutung</entry>
	  </row>
	</thead>

	<tbody>
	  <row>
	    <entry valign="top"><filename>articles</filename></entry>

	<entry>DocBook-formatierte Artikel (<tag>article</tag>)
	  oder ähnliche Dokumente.  Meist relativ kurz und in
	  Abschnitte aufgeteilt.  Artikel sind in der Regel als ein
	  einziges, großes <acronym>XHTML</acronym>-Dokument verfügbar.</entry>
	  </row>

	  <row>
	    <entry valign="top"><filename>books</filename></entry>

	<entry>DocBook-formatierte Bücher (<tag>book</tag>)
	  oder ähnliche Dokumente.  Umfangreiche Dokumente,
	  die in Kapitel aufgeteilt werden.  Sind in der Regel sowohl
	  als eine einzige, große <acronym>XHTML</acronym>-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.</entry>
	  </row>

	  <row>
	    <entry valign="top"><filename>man</filename></entry>

	<entry>Dient für Übersetzungen von Manualpages.  Es
	  enthält ein oder mehrere <filename
	  role="directory">man<replaceable>n</replaceable></filename>-Verzeichnisse,
	  je nachdem, welche Abschnitte der Manualpages bereits
	  übersetzt wurden.</entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>

    <para>Nicht jedes <filename
      role="directory"><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 xml: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 von
	DocBook <acronym>XML</acronym> (und der vom FreeBSD
	Project erweiterten <acronym>XML</acronym> DocBook-DTD)
	geschrieben.</para>

      <para>Das Handbuch ist als DocBook-<tag>book</tag>
	organisiert.  Es besteht aus mehreren Teilen
	(<tag>part</tag>s), die wiederum mehrere
	Kapitel (<tag>chapter</tag>) enthalten können.
	Kapitel sind zusätzlich in Abschnitte
	(<tag>sect1</tag>) und Unterabschnitte
	(<tag>sect2</tag>, <tag>sect3</tag> 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<acronym>XML</acronym>-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.xml</filename></title>

	  <para>Das Hauptdokument innerhalb des Handbuchs.  Neben der
	    <link
	    linkend="xml-primer-doctype-declaration">DOCTYPE-Deklaration</link>
	    des Handbuchs werden hier auch
	    die Elemente aufgelistet, die die Struktur des Handbuchs
	    definieren.</para>

	  <para><filename>book.xml</filename> verwendet <link linkend="xml-primer-parameter-entities">
	    Parameterentitäten</link>, um Dateien mit der
	    Endung <filename>.ent</filename> zu laden.  Diese
	    Dateien definieren die <link linkend="xml-primer-general-entities">allgemeinen
	    Entitäten</link>, die innerhalb des Handbuchs
	    verwendet werden.</para>
	</sect4>

	<sect4>
	   <title><filename
	    role="directory"><replaceable>Verzeichnis</replaceable>/chapter.xml</filename></title>

	  <para>Jedes Kapitel des Handbuchs wird in einer
	    <filename>chapter.xml</filename> genannten Datei
	    gespeichert.  Jedes Verzeichnis erhält den Namen
	    des <literal>id</literal>-Attributs des
	    <tag>chapter</tag>-Elements.</para>

	  <para>Enthält eine Kapiteldatei beispielsweise die
	    Einträge</para>

	  <programlisting><tag class="starttag">chapter id="kernelconfig"</tag>
...
<tag class="endtag">chapter</tag></programlisting>

	  <para>so handelt es sich um die Datei
	    <filename>chapter.xml</filename> im Verzeichnis
	    <filename>kernelconfig</filename>.  Im Allgemeinen
	    enthält diese Datei das komplette Kapitel.</para>

	  <para>Wird die <acronym>XHTML</acronym>-Version des Handbuchs
	    gebaut, entsteht dadurch
	    <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.xml</filename> gespeichert und nach dem
	    Wert des <literal>id</literal>-Attributs der
	    <tag>chapter</tag>-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>share/images/books/handbook</filename>
	    gespeichert.  Existiert eine lokalisierte Version eines
	    Bildes, wird diese hingegen gemeinsam mit dem
	    <acronym>XML</acronym>-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.xml</filename> enhalten,
	    beispielsweise <filename>basics/chapter.xml</filename>,
	    <filename>introduction/chapter.xml</filename> oder
	    <filename>printing/chapter.xml</filename>.</para>

	  <important>
	    <para>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).</para>
	  </important>

	  <para>Die Datei <filename>chapter.xml</filename> ist keine
	    komplette <acronym>XML</acronym>-Datei.  Dies bedeutet,
	    dass sie nicht alleine gebaut werden kann, sondern nur
	    als Teil des Handbuchs.</para>
	</sect4>
      </sect3>
    </sect2>
  </sect1>
</chapter>