Die Fibel für neue Mitarbeiter des FreeBSD-Dokumentationsprojekts
Zurück | Kapitel 6. Verzeichnisstruktur unter `doc/` | Weiter

# 6.3. Dokumentenspezifische Informationen

Dieser Abschnitt enthält Informationen zu einigen vom FreeBSD Documentation Project (FDP) verwalteten Dokumenten.

## 6.3.1. Das Handbuch

`books/handbook/`

Das Handbuch wurde unter Verwendung der vom FreeBSD Project erweiterten DocBook-DTD geschrieben.

Das Handbuch ist als DocBook-`<book>` organisiert. Es besteht aus mehreren Teilen (`<part>`s), die wiederum mehrere Kapitel (`<chapter>`) enthalten können. Kapitel sind zusätzlich in Abschnitte (`<sect1>`) und Unterabschnitte (`<sect2>`, `<sect3>` und so weiter) unterteilt.

### 6.3.1.1. Physikalische Organisation

Das Verzeichnis `handbook` enthält sowohl weitere Verzeichnisse als auch zahlreiche einzelne Dateien.

> Anmerkung: 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 FreeBSD documentation project.

#### 6.3.1.1.1. `Makefile`

Das `Makefile` 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-`doc.project.mk` inkludiert, die den für die Konvertierung in andere Formate notwendigen Code bereitstellt.

#### 6.3.1.1.2. `book.sgml`

Das Hauptdokument innerhalb des Handbuchs. Neben der DOCTYPE-Deklaration des Handbuchs werden hier auch die Elemente aufgelistet, die die Struktur des Handbuchs definieren.

`book.sgml` verwendet Parameterentitäten, um Dateien mit der Endung `.ent` zu laden. Diese Dateien definieren die allgemeinen Entitäten, die innerhalb des Handbuchs verwendet werden.

#### 6.3.1.1.3. ``Verzeichnis`/chapter.sgml`

Jedes Kapitel des Handbuchs wird in einer `chapter.sgml` 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.sgml` im Verzeichnis `kernelconfig`. Im Allgemeinen enthält diese Datei das komplette Kapitel.

Wird die HTML-Version des Handbuchs gebaut, entsteht dadurch die HTML-Datei `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.sgml` 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 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.

Durch dieses Vorgehen entstanden viele Verzeichnisse, die jeweils eine `chapter.sgml` enhalten, beispielsweise `basics/chapter.sgml`, `introduction/chapter.sgml` oder `printing/chapter.sgml`.

> Wichtig: 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.

Die Datei `chapter.sgml` ist keine komplette SGML-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.

Zurück | Zum Anfang | Weiter
Die Verzeichnisse ``Sprache`.`Kodierung`/` | Nach oben | Die Erzeugung der Zieldokumente

Wenn Sie Fragen zu FreeBSD haben, schicken Sie eine E-Mail an <de-bsd-questions@de.FreeBSD.org>.
Wenn Sie Fragen zu dieser Dokumentation haben, schicken Sie eine E-Mail an <de-bsd-translators@de.FreeBSD.org>.