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 verfügbar ist, verfügen manche Benutzer nur über eine langsame oder überhaupt keine Netzwerkverbindung. Es gibt mehrere Möglichkeiten, die lokale Kopie der Dokumentation durch die aktuelle FreeBSD-Dokumentationssammlung zu aktualisieren.

23.3.1. Verwenden von Subversion um die Dokumentation zu aktualisieren

Die Dokumentationsquellen von FreeBSD können mittels svn aktualisiert werden. Dieser Abschnitt beschreibt:

  • Die Installation der Dokumentations-Werkzeugsammlung, welche die Werkzeuge enthält, die nötig sind, um die FreeBSD Dokumentation aus den Quellen neu zu erstellen.

  • Das Herunterladen einer Kopie der Dokumentationsquellen nach /usr/doc, unter Verwendung von svn.

  • Den Bau der FreeBSD Dokumentation aus den Quellen und die Installation unter /usr/share/doc.

  • Manche der Optionen zum Erstellen, die vom System zum Bauen der Dokumentation unterstützt werden, z.B. die Optionen welche nur ein paar der unterschiedlichen Sprachübersetzungen der Dokumentation erstellen oder die Optionen, die ein bestimmtes Ausgabeformat auswählen.

23.3.2. svn und die Werkzeugsammlung der Dokumentation installieren

Die Erstellung der FreeBSD Dokumentation aus den Quellen benötigt eine große Anzahl an Werkzeugen, die nicht Teil des FreeBSD Basissystems sind, da sie eine große Menge Plattenplatz verbrauchen und nicht von allen FreeBSD-Anwendern benötigt werden. Sie sind daher nur für diejenigen Benutzer sinnvoll, die aktiv neue Dokumentation für FreeBSD schreiben oder häufig die Dokumentation aus den Quellen aktualisieren.

Alle benötigten Werkzeuge, einschließlich svn sind im Meta-Port textproc/docproj vorhanden, der vom FreeBSD Documentation Project entwickelt wurde.

Anmerkung:

Wenn Sie die Dokumentation nicht als PostScript® oder PDF benötigen, können Sie alternativ die Installation des textproc/docproj-nojadetex-Ports in Erwägung ziehen. Diese Version der Dokumentations-Werkzeugsammlung enthält alles ausser das teTeX-Textsatzsystem. teTeX ist eine sehr grosse Sammlung an Werkzeugen, deshalb ist es vernünftig, deren Installation auszulassen, wenn die Ausgabe von PDF nicht unbedingt gebraucht wird.

23.3.3. Die Dokumentationsquellen aktualisieren

In diesem Beispiel wird svn verwendet, um eine saubere Kopie der Dokumentationsquellen über das HTTPS-Protokoll zu holen:

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

Benutzen Sie dazu einen der Spiegel aus Subversion Mirror Sites.

Es dauert eine Weile, wenn die Dokumentationsquellen das allererste Mal heruntergeladen werden. Lassen Sie es laufen, bis es fertig ist.

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

# svn update /usr/doc

Nachdem die Quellen einmal ausgecheckt wurden, wird durch /usr/doc/Makefile ein alternativer Weg unterstützt, die Dokumentation zu aktualisieren. Geben Sie dazu die folgenden Befehle ein:

# cd /usr/doc
# make update

23.3.4. Einstellbare Optionen der Dokumentationsquellen

Das System zum aktualisieren und erstellen der FreeBSD-Dokumentationssammlung unterstützt ein paar Optionen, welche den Prozess der Aktualisierung von Teilen der Dokumentation oder einer bestimmten Übersetzung erleichtert. Diese Optionen können entweder systemweit in /etc/make.conf gesetzt, oder als Kommandozeilenoptionen an make(1) ü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, pdf, und rtf 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).

Für weitere make-Variablen, die vom System zum Erstellen der FreeBSD-Dokumentation unterstützt werden, lesen Sie die Fibel für neue Mitarbeiter des FreeBSD-Dokumentationsprojekts.

23.3.5. Die FreeBSD-Dokumentation aus den Quellen installieren

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, definiert in DOC_LANG, kann durch folgende Eingabe erreicht werden:

# cd /usr/doc
# make install clean

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

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

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

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

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

23.3.6. Verwendung von Dokumentations-Ports

Basierend auf der Arbeit von Marc Fonvieille.

Im vorherigen Abschnitt wurde eine Methode gezeigt, wie die FreeBSD-Dokumentation aus den Quellen gebaut werden kann. Allerdings sind quellbasierte Aktualisierungen möglicherweise nicht für alle FreeBSD-Systeme geeignet oder praktikabel. Das Erstellen der Dokumentationsquellen benötigt eine große Anzahl an Werkzeugen, Programmen und Hilfsmitteln, die documentation toolchain, einen gewissen Grad an Vertrautheit mit svn, ausgecheckte Quellen von einem Repository, sowie ein paar manuelle Schritte, um diese ausgecheckten Quellen zu bauen. Dieser Abschnitt beschreibt eine alternative Methode, in der die Ports-Sammlung verwendet wird und die es ermöglicht:

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

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

Diese beiden Methoden der Aktualisierung der FreeBSD-Dokumentation werden durch eine Menge von Dokumentations-Ports 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/).

23.3.6.1. Erstellen und Installieren von Dokumentations-Ports

Die Dokumentations-Ports nutzen das Ports-System, um das Erstellen von Dokumentation wesentlich einfacher zu machen. Es automatisiert den Prozess des Auscheckens der Dokumentationsquellen, aufrufen von make(1) mit den passenden Umgebungsvariablen und Kommandozeilenoptionen und macht die Installation und Deinstallation von Dokumentation so einfach wie die Installation von jedem anderen Port oder Paket.

Anmerkung:

Als zusätzliche Eigenschaft zeichnen sie eine Abhängigkeit zur Dokumentations-Werkzeugsammlung auf, wenn die Dokumentations-Ports lokal erstellt werden, weshalb diese auch automatisch mitinstalliert wird.

Die Dokumentations-Ports sind wie folgt organisiert:

  • Der Master-Port, misc/freebsd-doc-en, der alle englischen Dokumentations-Ports installiert.

  • Der Alles-in-Einem-Port, misc/freebsd-doc-all, welcher die komplette Dokumentation in allen verfügbaren Sprachen erstellt und installiert.

  • Es gibt noch einen Slave-Port für jede Übersetzung, beispielsweise misc/freebsd-doc-hu für Dokumentation in ungarischer Sprache.

Um die englische Dokumentation zu bauen im getrennten HTML-Format in /usr/local/share/doc/freebsd zu installieren, installieren Sie den folgenden Port:

# cd /usr/ports/misc/freebsd-doc-en
# make install clean
23.3.6.1.1. Gebräuchliche Schalter und Optionen

Es gibt viele Optionen, die das Standardverhalten der Dokumentations-Ports verändern. 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 gegebenenfalls book.html, zuzüglich der Bilder gespeichert.

WITH_PDF

Erstellt das Adobe® Portable Document Format (PDF). Die formatierte Dokumentation wird als Datei mit dem Namen article.pdf, oder gegebenenfalls als book.pdf gespeichert.

DOCBASE

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

Anmerkung:

Der Standardpfad zum Verzeichnis unterscheidet sich von dem Verzeichnis, das von svn verwendet wird. Das liegt daran, dass Ports üblicherweise in /usr/local installiert werden. Dies kann durch die Verwendung von PREFIX überschrieben werden.

Dieses Beispiel verwendet Variablen, um die ungarische Dokumentation als PDF zu installieren:

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

23.3.6.2. Verwendung von Dokumentations-Paketen

Das Erstellen der Dokumentations-Ports aus den Quellen, wie im vorherigen Abschnitt beschrieben, benötigt die lokale Installation der Dokumentations-Werkzeugsammlung und ein wenig Festplattenspeicher für das Bauen der Ports. Sollten die Ressourcen zum Bauen der Dokumentations-Werkzeugsammlung nicht zur Verfügung stehen, oder weil das erstellen zuviel Plattenplatz benötigen würde, ist es trotzdem möglich, bereits zuvor gebaute Schnappschüsse der Dokumentations-Ports zu installieren.

Documentation Engineering Team erstellt monatliche Schnappschüsse der Dokumentations-Pakete von FreeBSD. Diese Binärpakete können mit jedem der mitgelieferten Paketwerkzeuge installiert werden, beispielsweise pkg_add(1), pkg_delete(1) und so weiter.

Anmerkung:

Wenn Binärpakete zu Einsatz kommen, wird die FreeBSD-Dokumentation in allen verfügbaren Formaten in der gegebenen Sprache installiert.

Zum Beispiel installiert das folgende Kommando das aktuelle, vorgefertigte Paket der ungarischen Dokumentation:

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

23.3.6.3. Dokumentations-Ports aktualisieren

Dokumentations-Ports können wie jeder andere Port 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>.