FreeBSD handboek
Terug | Hoofdstuk 24. FreeBSD updaten en upgraden | Volgende

# 24.4. De documentatie bijwerken

Naast het basissysteem en de Portscollectie is documentatie een integraal onderdeel van het besturingssysteem FreeBSD. Hoewel een actuele versie van de FreeBSD-documentatie altijd beschikbaar is op de FreeBSD website, hebben sommige gebruikers een langzame of helemaal geen permanente netwerkverbinding. Gelukkig zijn er verschillende manieren om de documentatie die bij elke uitgave wordt geleverd bij te werken door een lokale kopie van de nieuwste FreeBSD-documentatie bij te houden.

## 24.4.1. CVSup gebruiken om de documentatie bij te werken

De bronnen en de geïnstalleerde kopie van de FreeBSD-documentatie kunnen met CVSup worden bijgewerkt, waarbij een mechanisme wordt gebruikt dat lijkt op degene die voor de broncode van het basissysteem wordt gebruikt (c.f. Paragraaf 24.7). Deze sectie beschrijft:

- Hoe de documentatiegereedschappen, de gereedschappen die nodig zijn om de FreeBSD-documentatie vanuit de broncode te herbouwen, te installeren.

- Hoe een kopie van de documentatiebronnen in `/usr/doc` te downloaden door CVSup te gebruiken.

- Hoe de FreeBSD-documentatie vanuit de broncode te herbouwen en onder `/usr/share/doc` te installeren.

- Sommige bouwopties die door het bouwsysteem van de documentatie ondersteund worden, i.e. de opties die slechts enkele van de verschillende vertalingen van de documentatie bouwen of de opties die een specifiek uitvoerformaat selecteren.

## 24.4.2. CVSup en de documentatiegereedschappen installeren

Voor het herbouwen van de FreeBSD-documentatie vanuit de broncode is een aardig grote verzameling gereedschappen nodig. Deze gereedschappen zijn geen deel van het basissysteem van FreeBSD omdat ze een grote hoeveelheid schijfruimte nodig hebben en niet voor alle FreeBSD-gebruikers nuttig zijn; ze zijn alleen nuttig voor die gebruikers die actief nieuwe documentatie voor FreeBSD schrijven of regelmatig hun documentatie vanuit de broncode bijwerken.

Alle benodigde gereedschappen zijn beschikbaar als deel van de Portscollectie. De port `textproc/docproj` is een meester-port die door het FreeBSD Documentatieproject is ontwikkeld om de installatie en toekomstige updates van deze gereedschappen makkelijker te maken.

> Opmerking: Wanneer er geen PostScript®- of PDF-documentatie nodig is, kan men overwegen om in plaats hiervan de port `textproc/docproj-nojadetex` te installeren. Deze versie van de documentatiegereedschappen bevat alles behalve de typesetting-engine teTeX. teTeX is een erg grote verzameling van gereedschappen, dus kan het zinvol zijn om de installatie ervan achterwege te laten als PDF-uitvoer niet echt nodig is.

Bekijk CVSup gebruiken voor meer informatie over het installeren en gebruiken van CVSup.

## 24.4.3. De documentatiebroncode bijwerken

Het hulpmiddel CVSup kan een schone kopie van de documentatiebroncode ophalen, door het bestand `/usr/share/examples/cvsup/doc-supfile` als een configuratiesjabloon te gebruiken. Voor de standaard update-host is in `doc-supfile` een nog in te vullen waarde ingevuld, maar cvsup(1) accepteert een hostnaam via de opdrachtregel, dus kan de documentatiebroncode van een van de CVSup-servers worden opgehaald door het volgende te typen:

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

Verander `cvsup.FreeBSD.org` in de dichtstbijzijnde CVSup-server. Zie Paragraaf A.6.7 voor een complete lijst van spiegelsites.

De initiële download van de documentatiebroncode kan een tijd duren. Laat het draaien totdat het voltooid is.

Toekomstige updates van de documentatiebroncode kunnen opgehaald worden door hetzelfde commando te draaien. Het hulpmiddel CVSup downloadt en kopieert alleen de updates sinds de laatste keer dat het gedraaid werd, dus zou elke keer dat CVSup gedraaid wordt na de eerste complete keer redelijk snel moeten zijn.

Nadat de broncode is uitgecheckt, wordt een alternatieve manier om de documentatie bij te werken ondersteund door `Makefile` van de map `/usr/doc`. Door `SUP_UPDATE`, `SUP_HOST`, en `DOCSUPFILE` in het bestand `/etc/make.conf` in te stellen, is het mogelijk om dit te draaien:

    # cd /usr/doc
    # make update

Een typische verzameling van deze make(1)-opties voor `/etc/make.conf` is:

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

> Opmerking: Het instellen van de waardes `SUPHOST` en `DOCSUPFILE` met `?=` staat toe dat ze in de opdrachtregel van make overschreven worden. Dit is de aangeraden manier om opties aan `/etc/make.conf` toe te voegen, om te voorkomen dat het bestand telkens wanneer er een andere waarde van de optie getest moet worden bewerkt moet worden.

## 24.4.4. Instelbare opties van de documentatiebroncode

Het bijwerk- en bouwsysteem van de FreeBSD-documentatie ondersteunt enkele opties die het proces om de documentatie alleen gedeeltelijk bij te werken, of om specifieke vertalingen te bouwen, makkelijker maken. Deze opties kunnen of als systeemwijde opties in het bestand `/etc/make.conf` worden ingesteld, of als opdrachtregelopties aan het hulpmiddel make(1) worden doorgegeven.

De volgende opties zijn er enkelen van:

`DOC_LANG`

  De lijst van te bouwen en te installeren talen en coderingen, bijvoorbeeld `en_US.ISO8859-1` voor alleen de Engelse documentatie.

`FORMATS`

  Een enkel formaat of een lijst van uitvoerformaten die gebouwd moeten worden. Momenteel worden `html`, `html-split`, `txt`, `ps`, `pdf`, en `rtf` ondersteund.

`SUPHOST`

  De hostnaam van de CVSup server die gebruikt wordt tijdens het bijwerken.

`DOCDIR`

  Waar de documentatie te installeren. Dit staat standaard op `/usr/share/doc`.

Bekijk make.conf(5) voor meer make-variabelen die als systeemwijde opties in FreeBSD worden ondersteund.

Voor meer make-variabelen die die door het bouwsysteem van de FreeBSD-documentatie ondersteund worden, wordt naar het FreeBSD Documentation Project Primer for New Contributors verwezen.

## 24.4.5. De FreeBSD-documentatie vanuit de broncode installeren

Wanneer er een actueel snapshot van de documentatiebroncode is opgehaald in `/usr/doc`, is alles gereed om de geïnstalleerde documentatie bij te werken.

Het volledig bijwerken van alle talen die in de Makefile-optie `DOC_LANG` zijn gedefinieerd kan worden gedaan door te typen:

    # cd /usr/doc
    # make install clean

Als `make.conf` is ingesteld met de juiste opties voor `DOCSUPFILE`, `SUPHOST`, en `SUP_UPDATE`, dan kan de installatiestap worden gecombineerd met het bijwerken van de documentatiebroncode door te typen:

    # cd /usr/doc
    # make update install clean

Als alleen het bijwerken van een specifieke taal gewenst is, dan kan make(1) worden aangeroepen in een taalspecifieke submap van `/usr/doc`, i.e.:

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

De te installeren uitvoerformaten kunnen worden gespecificeerd door de make-variabele `FORMATS` in te stellen, i.e.:

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

## 24.4.6. Documentatieports gebruiken

Gebaseerd op het werk van Marc Fonvieille.

In de vorige sectie werd er een methode voor het bijwerken van de FreeBSD-documentatie vanaf de broncode gepresenteerd. Het bijwerken gebaseerd op broncode is echter niet voor alle FreeBSD-systemen haalbaar of praktisch. Voor het bouwen van de documentatiebronnen zijn een redelijk grote verzameling van gereedschappen, de documentatie gereedschapskist, een bepaald niveau van bekendheid met CVS en checkouts van broncode vanuit een reservoir nodig, en een aantal handmatige stappen om de uitgecheckte broncode te bouwen. In deze sectie wordt een alternatieve manier beschreven om de geïnstalleerde kopiën van de FreeBSD-documentatie bij te werken; een die de Ports Collectie gebruikt en het mogelijk maakt om:

- Voorgebouwde versies van de documentatie te downloaden en te installeren, zonder iets lokaal te hoeven bouwen (op deze manier wordt de noodzaak voor een installatie van de gehele documentatie-gereedschapskist voorkomen).

- De documentatiebronnen te bouwen en ze via het ports-raamwerk te bouwen (de stappen van het uitchecken en bouwen worden iets eenvoudiger gemaakt).

Deze twee methoden om de FreeBSD-documentatie bij te werken worden ondersteund door een verzameling van documentatie-ports die maandelijks door het Documentatie Engineering Team `<doceng@FreeBSD.org>` worden bijgewerkt. Deze zijn vermeld in de FreeBSD Ports Collectie onder de virtuele categorie docs.

### 24.4.6.1. Documentatie-ports bouwen en installeren

De documentatie-ports gebruiken het bouwraamwerk van de ports om het bouwen van documentatie eenvoudiger te maken. Ze automatiseren het proces van het uitchecken van de broncode van de documentatie, het draaien van make(1) met de juiste omgevingsinstellingen en opdrachtregelopties, en ze maken de installatie of deïnstallatie van documentatie net zo eenvoudig als de installatie van elke andere FreeBSD-port of -pakket.

> Opmerking: Als een extra eigenschap registreren de documentatie-ports, wanneer ze lokaal zijn gebouwd, een afhankelijkheid naar de ports van de documentatie-gereedschapskist, zodat de laatste ook automatisch is geïnstalleerd.

De organisatie van de documentatie-ports is als volgt:

- Er is een “meester-port”, `misc/freebsd-doc-en`, waar de bestanden van de documentatie-ports gevonden kunnen worden. Het is de basis van alle documentatie-ports. Standaard bouwt het alleen de Engelstalige documentatie.

- Er is een “alles-in-één port”, `misc/freebsd-doc-all`, en het bouwt en installeert alle documentatie in alle beschikbare talen.

- Ten slotte is er een “slaaf-port” voor elke vertaling, b.v. `misc/freebsd-doc-hu` voor de documenten in het Hongaars. Ze zijn allemaal afhankelijk van de meester-port en installeren de vertaalde documentatie van de respectievelijke taal.

Gebruik de volgende commando's (als `root`) om een documentatieport vanaf de broncode te installeren:

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

Dit zal de Engelstalige documentatie in gesplitst HTML-formaat (hetzelfde als dat op http://www.FreeBSD.org wordt gebruikt) in de map `/usr/local/share/doc/freebsd` bouwen en installeren.

#### 24.4.6.1.1. Algemene knoppen en opties

Er zijn vele opties om het standaardgedrag van de documentatie-ports aan te passen. Het volgende is slechts een korte lijst:

`WITH_HTML`

  Staat bouwen van het HTML-formaat toe: een enkel HTML-bestand per document. De opgemaakte documentatie wordt naar gelang in een bestand genaamd `article.html`, of `book.html`, met afbeeldingen opgeslagen.

`WITH_PDF`

  Staat bouwen van het Adobe® Portable Document Format toe, te gebruiken met Adobe Acrobat Reader®, Ghostscript, of andere PDF-lezers. De opgemaakte documentatie wordt naar gelang opgeslagen in een bestand genaamd `article.pdf` of `book.pdf` opgeslagen.

`DOCBASE`

  Waar de documentatie te installeren. Standaard is dit `/usr/local/share/doc/freebsd`.

  > Opmerking: Merk op dat de standaard doelmap afwijkt van de map die door de CVSup-methode wordt gebruikt. Dit komt omdat er een port wordt geïnstalleerd, en ports worden normaliter onder de map `/usr/local` geïnstalleerd. Dit kan veranderd worden door de variabele `PREFIX` toe te voegen.

Hier is een kort voorbeeld over hoe de bovengenoemde variabelen te gebruiken om de Hongaarse documentatie in Portable Document Format te installeren:

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

### 24.4.6.2. Documentatiepakketten gebruiken

Voor het bouwen van de documentatie-ports vanaf broncode, zoals beschreven in de vorige sectie, is een lokale installatie van de documentatie-gereedschapskist en wat schijfruimte voor het bouwen van de ports nodig. Wanneer de bronnen voor het installeren van de documentatie-gereedschapskist niet aanwezig zijn, of wanneer het bouwen vanaf broncode te veel schijfruimte in beslag neemt, is het nog steeds mogelijk om de vooraf gebouwde versies van de documentatie-ports te installeren.

Het Documentatie Engineering Team `<doceng@FreeBSD.org>` bereidt maandelijkse versies van de FreeBSD documentatiepakketten voor. Deze binaire pakketten kunnen met elk van de meegeleverde pakketgereedschappen, zoals pkg_add(1), pkg_delete(1), enzovoorts gebruikt worden.

> Opmerking: Wanneer binaire pakketten worden gebruikt, zal de FreeBSD documentatie in alle beschikbare formaten voor de gegeven taal geïnstalleerd worden.

Het volgende commando bijvoorbeeld zal het nieuwste vooraf gebouwde pakket van de Hongaarse documentatie installeren:

    # pkg_add -r hu-freebsd-doc

> Opmerking: Pakketten hebben het volgende naamformaat welke afwijkt van de naam van de overeenkomstige port: ``taal`-freebsd-doc`. Hier is `taal` het korte formaat van de taalcode, i.e. `hu` voor Hongaars, of `zh_cn` voor Vereenvoudigd Chinees.

### 24.4.6.3. Documentatieports bijwerken

Voor het bijwerken van een eerder geïnstalleerde documentatieport is elk gereedschap voor het bijwerken van ports geschikt. Het volgende commando bijvoorbeeld werkt de geïnstalleerde Hongaarse documentatie bij via het gereedschap `ports-mgmt/portupgrade` door alleen pakketten te gebruiken:

    # portupgrade -PP hu-freebsd-doc

Terug | Begin | Volgende
Portsnap: een updategereedschap voor de Portscollectie | Omhoog | Een ontwikkelingstak volgen

Deze en andere documenten kunnen worden gedownload van ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

Lees voor vragen over FreeBSD de documentatie alvorens contact te zoeken <questions@FreeBSD.org>.
Vragen over deze documentatie kunnen per e-mail naar <doc@FreeBSD.org>.