Az alaprendszer és a Portgyűjtemény mellett a dokumentáció is a FreeBSD operációs rendszer szerves részét képezi. Noha a FreeBSD dokumentációjának legfrissebb változata folyamatosan elérhető a FreeBSD honlapjáról, egyes felhasználók ezt csak lassan vagy nem képesek folyamatosan elérni. Szerencsére egy helyi másolat megfelelő karbantartásával az egyes kiadásokhoz tartozó dokumentáció is frissíthető.
A FreeBSD telepített dokumentációjának forrásai az alaprendszeréhez hasonlóan (lásd 24.7. szakasz - Az alaprendszer újrafordítása) a CVSup segítségével frissíthetőek. Ebben a szakaszban megismerhetjük:
hogyan telepítsük a dokumentáció előállításához szükséges eszközöket, amelyekkel a forrásokból újra tudjuk generálni a FreeBSD dokumentációját;
hogyan töltsük le a dokumentáció
forrását CVSup
segítségével a /usr/doc
könyvtárba;
a dokumentáció előállításához alkalmazott rendszer milyen beállításokkal rendelkezik, vagyis hogyan korlátozzuk a generálást bizonyos nyelvekre vagy formátumokra.
Viszonylag sokféle eszközre lesz szükségünk, ha a FreeBSD dokumentációját a forrásokból akarjuk előállítani. Ezek az segédprogramok nem részei a FreeBSD alaprendszerének, mivel alapvetően nagyon sok helyet foglalnak el, és leginkább olyan FreeBSD felhasználók számára fontosak, akik folyamatosan a dokumentációval dolgoznak vagy gyakran frissítik azt forrásból.
A feladathoz szükséges összes eszköz elérhető a Portgyűjteményből. Ebben a FreeBSD Dokumentációs Projekt összeállított egy textproc/docproj nevű portot, amellyel az említett programok telepítését és frissítését igyekezték megkönnyíteni.
Ha nem tartunk igényt a dokumentáció PostScript(R) vagy PDF változatára, akkor ehelyett inkább érdemes megfontolnunk a textproc/docproj-nojadetex port telepítését. Ebben a változatban a teTeX betűszedő rendszer kivételével az összes segédprogram megtalálható. Mivel a teTeX önmagában nagyon sok segédeszköz telepítését jelenti, ezért amennyiben a PDF változat ténylegesen nem szükséges, érdemes eltekinteni a telepítésétől.
A CVSup telepítésével kapcsolatban pedig részletesebb információkat a CVSup használatával foglalkozó szakaszban olvashatunk.
A /usr/share/examples/cvsup/doc-supfile
konfigurációs állomány
segítségével a
CVSup képes letölteni a
dokumentáció
forrásállományainak legfrissebb
példányait. Itt a frissítést
alapértelmezés szerint egy nem létező
géptől fogjuk kérni (mivel ezt
kötelező kitölteni), azonban a cvsup(1)
programnak egy parancssori paraméter
segítségével megadhatjuk melyik
CVSup szerverről töltse le
a forrásokat:
#cvsup -h cvsup.FreeBSD.org -g -L 2 /usr/share/examples/cvsup/doc-supfile
Ne felejtsük el a
cvsup.FreeBSD.org helyére
beírni a hozzánk földrajzilag
legközelebb elhelyezkedő
CVSup szervert. Ezek teljes
listáját a A.6.7. szakasz - CVSup oldalak
tartalmazza.
Egy ideig eltarthat, amíg először letöltjük a forrásokat. Várjuk meg türelmesen, amíg befejeződik a művelet.
Később a forrásokat ugyanezzel a paranccsal tudjuk frissíteni. A CVSup ugyanis mindig csak a legutóbbi futtatása óta történt változásokat tölti le, ezért később már ez a lépés jelentősen felgyorsulhat.
A források letöltése után a
dokumentációt például az ekkor
keletkezett /usr/doc
könyvtárban található
Makefile használatával
állíthatjuk elő. Tehát miután
az /etc/make.conf állományban
beállítottuk a SUP_UPDATE,
SUPHOST és
DOCSUPFILE változókat, le
tudjuk futtatni a következő parancsot:
#cd /usr/doc#make update
Az előbb említett make(1) változók jellemző értékei:
SUP_UPDATE= yes SUPHOST?= cvsup.freebsd.org DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile
Mivel a SUPHOST és a
DOCSUPFILE változók
értékét a ?=
szimbólummal állítottuk be,
lehetőségünk van a parancssorból
ezeknek más értékeket adni. Az
/etc/make.conf állományba
általában így érdemes felvenni a
változókat, így nem kell minden
alkalommal módosítani, amikor valamilyen
új beállítást akarunk
kipróbálni.
A FreeBSD dokumentációjához
tartozó, frissítést és
előállítást végző
rendszernek van néhány olyan
beállítása, amelyekkel
kérhetjük kizárólag csak a
dokumentáció egyes részeinek
frissítését vagy bizonyos kimeneti
formátumok használatát. Ezek vagy
globálisan az /etc/make.conf
állományban, vagy pedig a parancssorból, a
make(1) program paramétereként
adhatóak meg.
Ízelítőül néhány közülük:
DOC_LANGAz előállítandó és
telepítendő nyelvű
dokumentáció felsorolása, tehát
például csak az angol
dokumentáció esetén ez
en_US.ISO8859-1.
FORMATSAz előállítandó
dokumentáció kimeneti formátumainak
felsorolása. Itt pillanatnyilag
értékként a html,
html-split, txt,
ps, pdf és
rtf jelenhet meg.
SUPHOSTA frissítéshez használt CVSup szerver hálózati neve.
DOCDIRAz elkészült dokumentáció
telepítésének helye. Ez
alapértelmezés szerint a /usr/share/doc.
A folyamathoz kapcsolódóan további rendszerszintű make(1) változókról a make.conf(5) man oldalon olvashatunk.
A FreeBSD dokumentációjának előállításáért felelős rendszerben használható make(1) további változók bemutatásával kapcsolatban pedig olvassuk el az A FreeBSD Dokumentációs Projekt irányelvei kezdőknek című könyvet.
Miután sikerült letöltenünk a
/usr/doc
könyvtárba a dokumentáció legfrissebb
forrásait, készen állunk a
rendszerünkön telepített példány
frissítésére.
A DOCLANG értékeként
megadott nyelven készült dokumentációkat
a következő paranccsal tudjuk
frissíteni:
#cd /usr/doc#make install clean
Ha a make.conf
állományban korábban már megadtuk a
DOCSUPFILE, SUPHOST
és SUP_UPDATE változók
értékeit, akkor a telepítés
fázisa könnyedén össze is
vonatható a források
frissítésével:
#cd /usr/doc#make update install clean
Ha pedig csak bizonyos nyelvekhez tartozó
dokumentációt szeretnénk frissíteni,
akkor a make(1) akár a /usr/doc könyvtáron
belül az egyes nyelvekhez tartozó
alkönyvtárakon belül is
meghívható, például:
#cd /usr/doc/en_US.ISO8859-1#make update install clean
A dokumentáció formátumát a
FORMATS változó
felhasználásával tudjuk
meghatározni:
#cd /usr/doc#make FORMATS='html html-split' install clean
Ez előző szakaszban megmutattuk hogyan lehet a FreeBSD dokumentációját a források felhasználásával frissíteni. A források használatával végzett frissítés azonban nem minden FreeBSD rendszer esetében lehetséges vagy hatékony. Ha ugyanis a dokumentációs forrásból akarjuk előállítani, viszonylag sok eszköz és segédprogram, az ún. dokumentációs eszközök használatával kell tisztában lennünk, valamint bizonyos mértékig ismernünk kell a CVS használatát, tudunk kell kikérni a legfrissebb változatot és előállítatattnunk belőle a végleges változatot. Ezért ebben a szakaszban most szót ejtünk egy olyan módszerről, ahol a FreeBSD dokumentációját a Portgyűjteményen keresztül tudjuk frissíteni, ezáltal:
anélkül le tudjuk tölteni és telepíteni a dokumentáció adott pillanatban generált változatát, hogy a rendszerünkön bármi további teendőre szükség lenne (ennek köszönhetően nem kell telepítenünk a dokumentációs eszközöket);
letölthetjük a dokumentáció forrását és a Portgyűjtemény eszközeivel előállíthatjuk belőle a megfelelő változatot (ez a források beszerzésében és feldolgozásában segít valamelyest).
A FreeBSD dokumentáció
frissítésének fentebb említett
módjait támogatják tehát a
dokumentációs portok,
amelyeket a Documentation Engineering Team <doceng@FreeBSD.org> havi rendszerességgel tart karban.
Ezek a portok a FreeBSD Portgyűjteményén
belül a docs nevű
virtuális kategóriában
találhatóak meg.
A dokumentáció könnyebb előállításához a dokumentációs portok a Portgyűjtemény lehetőségeit veszik igénybe. Segítségükkel automatikussá teszik a dokumentáció forrásának letöltését, a make(1) parancs meghívását a megfelelő környezetben, beállításokkal és parancssori paraméterekkel. Rajtuk keresztül a dokumentáció eltávolítása ugyanolyan egyszerűen megtehető, mint akármelyik másik FreeBSD port vagy csomag esetében.
Továbbá, amikor a dokumentációs portokat a saját rendszerünkön fordítjuk, a dokumentációs eszközök függőségként automatikusan települni fognak.
A dokumentációs portok a következő módon szerveződnek:
Létezik egy ún. "főport", a misc/freebsd-doc-en, ahol az összes fontosabb állomány megtalálható. Ez lényegében a dokumentációs portok közös őse. Alapértelmezés szerint kizárólag csak az angol nyelvű dokumentációt állítja elő.
Létezik egy "mindenes port", a misc/freebsd-doc-all, amely az összes elérhető nyelven és formátumban előállítja a dokumentációt.
Végezetül minden nyelvhez létezik egy-egy "alport", ilyen például a magyar dokumentáció esetén a misc/freebsd-doc-hu port. Mindegyikük a főporttól függ és az adott nyelvű dokumentációt telepítik.
Az eddigi összefoglaltaknak megfelelően a
dokumentációs portokat forrásból a
következő paranccsal lehet telepíteni
(root
felhasználóként):
#cd /usr/ports/misc/freebsd-doc-en#make install clean
Ennek hatására előáll és
telepítődik a /usr/local/share/doc/freebsd
könyvtárba az angol nyelvű
dokumentáció állományokra bontott
HTML formátumban (hasonlóan a
http://www.FreeBSD.org
tartalmához).
A dokumentációs portok alapértelmezett viselkedése több különböző opció segítségével is befolyásolható. Ezek közül most összefoglalunk néhányat:
WITH_HTMLMinden dokumentum egyetlen HTML
állományba kerüljön. A
végeredmény ekkor az adott dokumentum
típusának megfelelően
article.html (cikk) vagy
book.html (könyv)
néven keletkezik (képekkel
együtt).
WITH_PDFMinden dokumentum Adobe(R) Portable Document Format
típusú állományban
jön létre. Ezek az
állományok a
Ghostscript vagy más
egyéb PDF nézegetőkkel
nyithatóak meg. Ekkor a
dokumentáció konkrét
típusától függően az
állományok
article.pdf (cikk) vagy
book.pdf (könyv)
néven állítódnak
elő.
DOCBASEA dokumentáció
telepítésének helye.
Alapértelmezés szerint ez a /usr/local/share/doc/freebsd
könyvtár.
Ügyeljünk arra, hogy a
telepítés alapértelmezett
célkönyvtára eltér a
CVSup
módszerétől. Ugyanis mivel
ilyenkor egy portot telepítünk, a
tartalma alapértelmezés szerint a
/usr/local
könyvtáron belülre kerül.
Ez azonban a PREFIX
változó
átállításával
tetszőleges
megváltoztatható.
Az előbbieket most egy rövid példán keresztül összefoglaljuk. A következő paranccsal tudjuk tehát a magyar nyelvű dokumentáció Portable Document Format változatát telepíteni:
#cd /usr/ports/misc/freebsd-doc-hu#make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean
A dokumentációs portok előző szakaszban bemutatott forrásból telepítésével kapcsolatban már említettük, hogy szükséges hozzá a dokumentációs eszközök telepítése, valamint némi szabad tárterület. Ha a dokumentációs eszközök telepítéséhez nem elengedőek a rendelkezésre álló erőforrásaink vagy a források feldolgozása túlságosan sokat foglalna a rendszerünkön, akkor lehetőségünk van a dokumentációs portok előre lefordított, csomagolt változatát használni.
A Documentation Engineering Team <doceng@FreeBSD.org> minden hónapban
előkészíti a FreeBSD dokumentációs
csomagok legfrissebb változatát. Az így
karbantartott bináris csomagok azután
tetszőlegesen használhatóak a
szabványos csomagkezelő eszközökkel,
mint amilyen például a pkg_add(1),
pkg_delete(1) és így tovább.
A bináris csomagok használata esetén a FreeBSD dokumentációja az adott nyelvhez az összes elérhető formátumban telepítésre kerül.
Például az alábbi paranccsal a magyar nyelvű dokumentációhoz tartozó legfrissebb bináris csomagot tudjuk telepíteni:
#pkg_add -r hu-freebsd-doc
A csomagok elnevezése eltér a
hozzá tartozó port nevétől. Alakja a
következő:
nyelv-freebsd-doc,
ahol a nyelv az adott nyelv
rövid kódja, vagyis a magyar esetén a
hu, illetve az egyszerűsített
kínai esetén a
zh_ch.
Az előzetesen telepített dokumentációs portok bármilyen portok frissítésére alkalmas eszközzel frissíthetőek. Például a telepített magyar nyelvű dokumentáció a ports-mgmt/portupgrade eszközön keresztül így frissíthető csomagok használatával:
#portupgrade -PP hu-freebsd-doc
Ha kérdése van a FreeBSD-vel kapcsolatban, a
következő címre írhat (angolul):
<questions@FreeBSD.org>.
Ha ezzel a dokumentummal kapcsolatban van kérdése, kérjük erre a címre írjon:
<gabor@FreeBSD.org>.