Das FreeBSD-Handbuch
Zurück | Kapitel 25. FreeBSD aktualisieren | Weiter

# 25.4. Aktualisieren der Dokumentationssammlung

Übersetzt von Benedict Reuschling.

Neben dem Basissystem und der Ports-Sammlung ist die 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. Glücklicherweise gibt es mehrere Möglichkeiten, die Dokumentation, welche mit jeder Version ausgeliefert wird, zu aktualisieren, indem eine lokale Kopie der aktuellen FreeBSD-Dokumentationssammlung verwendet wird.

## 25.4.1. Verwenden von CVSup um die Dokumentation zu aktualisieren

Die Quellen und die installierte Kopie der FreeBSD Dokumentation kann mittels CVSup aktualisiert werden, indem ein ähnlicher Mechanismus angewendet wird, wie derjenige für die Betriebssystemquellen (vergleichen Sie mit Abschnitt 25.7). Dieser Abschnitt beschreibt:

- Wie die Dokumentations-Werkzeugsammlung installiert wird, welche die Werkzeuge enthält, die nötig sind, um die FreeBSD Dokumentation aus den Quellen neu zu erstellen.

- Wie man eine Kopie der Dokumentationsquellen nach `/usr/doc` herunterlädt, unter Verwendung von CVSup.

- Wie man die FreeBSD Dokumentation aus den Quellen baut und unter `/usr/share/doc` installiert.

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

## 25.4.2. CVSup und die Werkzeugsammlung der Dokumentation installieren

Die FreeBSD Dokumentation aus dem Quellen zu erstellen benötigt eine ziemlich grosse Anzahl an Werkzeugen. Diese Werkzeuge sind nicht Teil des FreeBSD Basissystems, da sie eine grosse Menge an Plattenplatz verbrauchen und nicht von allen FreeBSD-Anwendern benötigt werden. Sie sind nur für diejenigen Benutzer notwendig, die aktiv an neuer Dokumentation fü FreeBSD schreiben oder häufig ihre Dokumentation aus den Quellen bauen lassen.

Alle benötigten Werkzeuge sind als Teil der Ports-Sammlung verfügbar. Der Port `textproc/docproj` dient als Masterport, der vom FreeBSD Documentation Project entwickelt wurde, um die initiale Installation und zukünftige Aktualisierungen dieser Werkzeuge zu vereinfachen.

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

Für weitere Informationen über das Installieren und Verwenden von CVSup, lesen Sie CVSup verwenden.

## 25.4.3. Die Dokumentationsquellen aktualisieren

Das Programm CVSup kann eine saubere Kopie der Dokumentationsquellen holen, indem es die Datei `/usr/share/examples/cvsup/doc-supfile` als Konfigurationsvorlage verwendet. Der Standard-Host zum Aktualisieren ist auf einen Platzhalterwert im `doc-supfile` gesetzt, aber cvsup(1) akzeptiert auch einen Hostnamen über die Kommandozeile. Somit können die Dokumentationsquellen von einem der CVSup-Server geholt werden, indem man eingibt:

    # cvsup -h cvsup.FreeBSD.org -g -L 2 /usr/share/examples/cvsup/doc-supfile

Ändern Sie `cvsup.FreeBSD.org` auf den Ihnen am nächsten gelegenen CVSup-Server. Eine vollständige Liste von Spiegelservern finden Sie unter Abschnitt A.6.7.

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 Sie über den gleichen Befehl bekommen. Das Programm CVSup lädt und kopiert nur diejenigen Aktualisierungen herunter, die seit seinem letzten Aufruf hinzugekommen sind. Deshalb sollte jeder weitere Aufruf von CVSup nach dem Ersten wesentlich schneller abgeschlossen sein.

Nachdem die Quellen einmal ausgecheckt wurden, besteht ein anderer Weg, die Dokumentation zu aktualisieren, darin, das `Makefile` im Verzeichnis `/usr/doc` anzupassen. Durch setzen von `SUP_UPDATE`, `SUPHOST` und `DOCSUPFILE` in der Datei `/etc/make.conf` ist es jetzt möglich, folgendes zu tun:

    # cd /usr/doc
    # make update

Ein typischer Satz dieser make(1)-Optionen für `/etc/make.conf` ist:

    SUP_UPDATE= yes
    SUPHOST?= cvsup.freebsd.org
    DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile

> Anmerkung: Das Setzen des Werts von `SUPHOST` und `DOCSUPFILE` auf `?=` erlaubt es, diese in der Kommandozeile von make zu überschreiben. Diese Methode wird empfohlen, um Optionen zu `make.conf` hinzuzufügen, um zu verhindern, dass man die Datei jedes Mal bearbeiten muss, um einen anderen Wert für die Option auszuprobieren.

## 25.4.4. Einstellbare Optionen der Dokumentationsquellen

Das System zum aktualisieren und erstellen der FreeBSD-Dokumentation unterstützt ein paar Optionen, welche den Prozess der Aktualisierung von Teilen der Dokumentation oder einer bestimmten Übersetzung erleichtert. Diese Optionen lassen sich entweder systemweit in der Datei `/etc/make.conf` setzen, oder als Kommandozeilenoptionen, die dem make(1)-Werkzeug übergeben werden.

Die folgenden Optionen sind ein paar davon:

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

`SUPHOST`

  Der Hostname des CVSup-Servers, der verwendet werden soll, um Aktualisierungen zu holen.

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

## 25.4.5. Die FreeBSD-Dokumentation aus den Quellen installieren

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

Eine komplette Aktualisierung aller Sprachoptionen, definiert durch die `DOC_LANG` Makefile-Option, kann durch folgende Eingabe erreicht werden:

    # cd /usr/doc
    # make install clean

Wenn `make.conf` mit den richtigen Optionen `DOCSUPFILE`, `SUPHOST` und `SUP_UPDATE` eingerichtet wurde, kann der Installationsschritt mit einer Aktualisierung der Dokumentationsquellen kombiniert werden, indem man eingibt:

    # cd /usr/doc
    # make update install clean

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

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

Die zu installierenden Ausgabeformate können durch das Setzen der make-Variablen `FORMATS` angegeben werden, z.B.:

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

## 25.4.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 grosse Anzahl an Werkzeugen, Programmen und Hilfsmitteln, die documentation toolchain, ein gewisser Grad an Vertrautheit mit CVS und ausgecheckte Quellen von einem Repository, sowie ein paar manuelle Schritte, um diese ausgecheckten Quellen zu bauen. In diesem Abschnitt wird eine alternative Art und Weise vorgestellt, wie man die installierte Kopie der FreeBSD-Dokumentation aktualisieren kann. Diese Methode verwendet die Ports-Sammlung und erlaubt es:

- vorgefertigte Schnappschüsse der Dokumentation herunter zu laden und zu installieren, ohne vorher irgendetwas lokal zu erstellen (dadurch ist es nicht mehr notwendig, den kompletten Werkzeugkasten der Dokumentation zu installieren).

- 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 `<doceng@FreeBSD.org>` monatlich aktualisiert wird. Diese sind in der Ports-Sammlung unter der virtuellen Kategorie, docs genannt, gelistet.

### 25.4.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 zum Dokumentations-Werkzeugsatz auf, wenn die Dokumentations-Ports lokal erstellt werden, weshalb dieser auch automatisch mitinstalliert wird.

Die Dokumentations-Ports sind wie folgt organisiert:

- Es existiert ein “Master-Port”, `misc/freebsd-doc-en`, in dem alle Dateien zu den Dokumentations-Ports abgelegt sind. Es dient als Basis für alle Dokumentations-Ports. Als Voreinstellung wird nur die englische Dokumentation gebaut.

- Es gibt einen “Alles-in-Einem-Port”, `misc/freebsd-doc-all`, welcher die komplette Dokumentation in allen verfügbaren Sprachen erstellt und installiert.

- Schliesslich gibt es noch einen sogenannten “slave port” f&¨r jede Übersetzung, z.B.: `misc/freebsd-doc-hu` für Dokumentation in ungarischer Sprache. All diese benötigen den Master-Port und installieren die übersetzte Dokumentation in der entsprechenden Sprache.

Um einen Dokumentations-Port aus den Quellen zu installieren, geben Sie das folgende Kommando (als `root`) ein:

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

Auf diese Weise wird die englische Dokumentation gebaut und als getrenntes HTML-Format im Verzeichnis `/usr/local/share/doc/freebsd` installiert (genau wie unter http://www.FreeBSD.org zu finden).

#### 25.4.6.1.1. Gebräuchliche Schalter und Optionen

Es gibt viele Optionen, um das Standarderhalten der Dokumentations-Ports zu verändern. Im Folgenden sind nur ein paar davon aufgeführt:

`WITH_HTML`

  Erlaubt das Erstellen im HTML-Format: eine einzige HTML-Datei pro Dokument. Die formatierte Dokumentation wird als Datei mit dem Namen `article.html` gespeichert, oder, je nachdem, als `book.html`, zuzuüglich der Bilder.

`WITH_PDF`

  Erlaubt das Erstellen von Adobe® Portable Document Format, für die Verwendung mit Adobe Acrobat Reader®, Ghostscript oder anderen PDF-Betrachtern. Die formatierte Dokumentation wird als Datei mit dem Namen `article.pdf` oder, soweit angemessen, als `book.pdf` gespeichert.

`DOCBASE`

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

  > Anmerkung: Beachten Sie, dass sich der Standardpfad von dem Verzeichnis unterscheidet, das von der CVSup-Methode verwendet wird. Das liegt daran, dass ein Port installiert wird und diese üblicherweise im Verzeichnis `/usr/local` abgelegt werden. Durch setzen der `PREFIX`-Variablen kann dieses Verhalten geändert werden.

Es folgt ein kurzes Beispiel, wie die Variablen verwendet werden, um die oben erwähnte ungarische Dokumentation als Portable Document Format zu installieren:

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

### 25.4.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 `<doceng@FreeBSD.org>` 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_add -r hu-freebsd-doc

> Anmerkung: Pakete haben das folgende Namensformat, 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.

### 25.4.6.3. Dokumentations-Ports aktualisieren

Um einen zuvor installierten Dokumentations-Port zu aktualisieren, kann jedes Werkzeug, das auch zum Aktualisieren von Ports verwendet wird, eingesetzt werden. Beispielsweise aktualisiert das folgende Kommando die installierte ungarische Dokumentation mittels des Programms `ports-mgmt/portupgrade` indem nur Pakete verwendet werden sollen:

    # portupgrade -PP hu-freebsd-doc

Zurück | Zum Anfang | Weiter
Portsnap: Ein Werkzeug zur Aktualisierung der Ports-Sammlung | Nach oben | Einem Entwicklungszweig folgen

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