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.
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.
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 meesterport 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.
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.
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:
De lijst van te bouwen en te installeren talen en coderingen, bijvoorbeeld en_US.ISO8859-1 voor alleen de Engelse documentatie.
Een enkel formaat of een lijst van uitvoerformaten die gebouwd moeten worden. Momenteel worden html, html-split, txt, ps, pdf, en rtf ondersteund.
De hostnaam van de CVSup server die gebruikt wordt tijdens het bijwerken.
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.
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
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>.