24.4. A dokumentáció frissítése
Vissza | 24. fejezet - A FreeBSD frissítése és frissen tartása | Előre

## 24.4. A dokumentáció frissítése

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

### 24.4.1. A dokumentáció frissítése CVSup használatával

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.

### 24.4.2. A CVSup és a dokumentációs eszközök telepítése

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.

### Megjegyzés:

Ha nem tartunk igényt a dokumentáció PostScript® 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.

### 24.4.3. A dokumentáció forrásának frissítése

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

### Megjegyzés:

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.

### 24.4.4. A dokumentáció különböző beállításai

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

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

`FORMATS`

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

`SUPHOST`

  A frissítéshez használt CVSup szerver hálózati neve.

`DOCDIR`

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

### 24.4.5. A FreeBSD dokumentációjának telepítése forrásból

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

### 24.4.6. A dokumentációs portok használata

A szóbanforgó megoldást fejlesztette: Fonvieille, Marc.

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.

#### 24.4.6.1. A dokumentációs portok fordítása és telepítése

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.

### Megjegyzés:

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

##### 24.4.6.1.1. Gyakori beállítások

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

  Minden 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_PDF`

  Minden dokumentum Adobe® 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ő.

`DOCBASE`

  A dokumentáció telepítésének helye. Alapértelmezés szerint ez a `/usr/local/share/doc/freebsd` könyvtár.

  ### Megjegyzés:

  Ü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

#### 24.4.6.2. A dokumentációs csomagok használata

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.

### Megjegyzés:

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

### Megjegyzés:

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

#### 24.4.6.3. A dokumentációs portok frissítése

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

Vissza | Fel | Előre
24.3. A Portgyűjtemény frissítése a Portsnap használatával | Főoldal | 24.5. A fejlesztői ág követése

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