23.3. Aktualisieren der Dokumentationssammlung

Übersetzt von Benedict Reuschling.

Dokumentation ein wichtiger Bestandteil des FreeBSD Betriebssystems. Obwohl eine aktuelle Version der FreeBSD Dokumentation jederzeit auf der FreeBSD Webseite ( http://www.freebsd.org/doc/) verfügbar ist, kann es nützlich sein, eine lokale Kopie der FreeBSD Webseite, Handbücher, FAQ und Artikel zu haben.

Dieser Abschnitt beschreibt, wie Sie die FreeBSD Dokumentation über die Quellen oder die FreeBSD Ports-Sammlung aktuell halten.

Informationen zum Bearbeiten und Einreichen von Korrekturen finden Sie in der Fibel für neue Mitarbeiter des FreeBSD-Dokumentationsprojekts.

23.3.1. Die FreeBSD-Dokumentation aus den Quellen installieren

Der Bau der FreeBSD Dokumentation aus den Quellen erfordert einige Werkzeuge, die nicht Teil des Basissystems sind. Die erforderlichen Werkzeuge, darunter auch svn, können über den Port oder das Paket textproc/docproj installiert werden.

Benutzen Sie nach der Installation svn, um eine saubere Kopie der Dokumentationsquellen zu holen:

# svn checkout https://svn.FreeBSD.org/doc/head /usr/doc

Es dauert eine Weile, bis die Quellen das allererste Mal heruntergeladen werden. Lassen Sie den Vorgang laufen, bis es fertig ist.

Zukünftige Aktualisierungen der Dokumentationsquellen können wie folgt durchgeführt werden:

# svn update /usr/doc

Sobald ein aktueller Schnappschuss der Dokumentationsquellen nach /usr/doc heruntergeladen wurde, ist alles bereit für eine Aktualisierung der bestehenden Dokumentation.

Eine komplette Aktualisierung aller Sprachen kann durch folgende Eingabe erreicht werden:

# cd /usr/doc
# make install clean

Wenn nur eine Aktualisierung einer bestimmten Sprache gewünscht wird, kann make in einem sprachspezifischen Unterverzeichnis von /usr/doc aufgerufen werden:

# cd /usr/doc/en_US.ISO8859-1
# make install clean

Alternativ kann der folgende Befehl in /usr/doc oder einem sprachspezifischen Unterverzeichnis abgesetzt werden, um die Dokumentation zu aktualisieren:

# make update

Die zu installierenden Ausgabeformate können durch das Setzen von FORMATS angegeben werden:

# cd /usr/doc
# make FORMATS='html html-split' install clean

Es existieren ein paar Optionen, welche den Prozess der Aktualisierung von Teilen der Dokumentation oder einer bestimmten Übersetzung erleichtern. Diese Optionen können entweder systemweit in /etc/make.conf gesetzt, oder als Kommandozeilenoptionen an make übergeben werden.

Zu den Optionen gehören:

DOC_LANG

Eine Liste von Sprachen und Kodierungen, die gebaut und installiert werden sollen, z.B. en_US.ISO8859-1, um nur die englische Dokumentation zu erhalten.

FORMATS

Ein einzelnes Format oder eine Liste von Ausgabeformaten, das gebaut werden soll. Momentan werden html, html-split, txt, ps und pdf unterstützt.

DOCDIR

Wohin die Dokumentation installiert werden soll. Der Standardpfad ist /usr/share/doc.

Für weitere make-Variablen, die als systemweite Optionen in FreeBSD unterstützt werden, lesen Sie make.conf(5).

23.3.2. Die Dokumentation aus den Ports aktualisieren

Basierend auf der Arbeit von Marc Fonvieille.

Im vorherigen Abschnitt wurde eine Methode gezeigt, wie die FreeBSD-Dokumentation aus den Quellen gebaut werden kann. Dieser Abschnitt beschreibt eine alternative Methode, in der die Ports-Sammlung verwendet wird und die es ermöglicht:

  • vorgefertigte Schnappschüsse der Dokumentation zu installieren, ohne vorher die Werkzeugsammlung der Dokumentation installieren zu müssen.

  • die Dokumentationsquellen durch das Ports-System erstellen zu lassen, was die Schritte zum Auschecken und Erstellen etwas erleichtert.

Diese Methoden der Aktualisierung der FreeBSD-Dokumentation werden durch eine Menge von Dokumentations-Ports und Paketen unterstützt, die von Documentation Engineering Team monatlich aktualisiert wird. Diese sind in der FreeBSD Ports-Sammlung unter der Kategorie docs gelistet ( http://www.freshports.org/docs/).

Die Dokumentations-Ports sind wie folgt organisiert:

  • Das Paket oder der Port misc/freebsd-doc-en installiert die englische Dokumentation.

  • Das Paket oder der Port misc/freebsd-doc-all installiert die komplette Dokumentation in allen verfügbaren Sprachen.

  • Es gibt noch ein Paket oder einen Port für jede Übersetzung, beispielsweise misc/freebsd-doc-hu für die ungarische Dokumentation.

Wenn Sie Pakete benutzen, wird die FreeBSD-Dokumentation in allen verfügbaren Formaten der jeweiligen Sprache installiert. Das folgende Beispiel wird das aktuelle Paket der ungarischen Dokumentation installieren:

# pkg install hu-freebsd-doc

Anmerkung:

Pakete verwenden ein Format, welches sich von dem Namen des dazugehörigen Ports unterscheidet: lang-freebsd-doc. lang entspricht hier der Kurzform des Sprachcodes, z.B. hu für Ungarisch, oder zh_cn für vereinfachtes Chinesisch.

Um das Format der Dokumentation zu bestimmen, muss anstelle des Pakets der Port gebaut werden. Das folgende Beispiel baut und installiert die englische Dokumentation:

# cd /usr/ports/misc/freebsd-doc-en
# make install clean

Der Port enthält ein Konfigurationsmenü, in dem das Format ausgewählt werden kann. In der Voreinstellung sind html-split und pdf ausgewählt.

Alternativ können bei der Erstellung eines Dokumentations-Ports verschiedene make-Optionen angegeben werden. Dazu gehören:

WITH_HTML

Erstellt das HTML-Format mit einer einzigen HTML-Datei pro Dokument. Die formatierte Dokumentation wird als Datei mit dem Namen article.html oder book.html gespeichert.

WITH_PDF

Die formatierte Dokumentation wird als Datei mit dem Namen article.pdf oder book.pdf gespeichert.

DOCBASE

Legt den Pfad fest, wohin die Dokumentation installiert werden soll. Die Voreinstellung ist /usr/local/share/doc/freebsd.

Dieses Beispiel verwendet Variablen, um die ungarische Dokumentation als PDF in ein bestimmtes Verzeichnis zu installieren:

# cd /usr/ports/misc/freebsd-doc-hu
# make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean

Dokumentations-Ports oder -Pakete können nach den Anweisungen in Kapitel 4, Installieren von Anwendungen: Pakete und Ports aktualisiert werden. Beispielsweise aktualisiert das folgende Kommando die installierte ungarische Dokumentation mittels ports-mgmt/portmaster unter Verwendung von Paketen:

# portmaster -PP hu-freebsd-doc

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