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 van de FreeBSD-documentatie kunnen met Subversion worden bijgewerkt. 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
Subversion 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 meester-port
die door het FreeBSD Documentatieproject is ontwikkeld om de
installatie en toekomstige updates van deze gereedschappen
makkelijker te maken.
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.
Subversion wordt geïnstalleerd met de
port textproc/docproj
.
Het programma Subversion kan een schone kopie van de documentatiebroncode ophalen door het volgende te typen:
#
svn checkout svn://svn.FreeBSD.org/doc/head
/usr/doc
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 het volgende commando te draaien:
#
svn update /usr/doc
Nadat de broncode is uitgecheckt, wordt een alternatieve
manier om de documentatie bij te werken ondersteund door
Makefile
van de map /usr/doc
door het volgende te
draaien:
#
cd /usr/doc
#
make update
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.
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 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 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
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 Subversion 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.
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.
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, bijvoorbeeld 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.
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
.
Merk op dat de standaard doelmap afwijkt van de map die
door de Subversion-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 cleanVoor 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.
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
Pakketten hebben het volgende naamformaat welke afwijkt
van de naam van de overeenkomstige port:
.
Hier is taal
-freebsd-doctaal
het korte formaat
van de taalcode, i.e., hu
voor Hongaars,
of zh_cn
voor Vereenvoudigd Chinees.
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