Ebben a fejezetben szeretnénk pontosan tisztázni hogyan szerveződik a dokumentáció előállításának folyamata és hogyan tudunk ebbe beavatkozni. A fejezet elolvasása során megismerjük: az SGML eszközeiről szóló fejezetben említetteken túl a &os; Dokumentációs Projekt keretein belül készített dokumentáció különböző változatainak előállításához mire van még szükségünk; a dokumentumokhoz tartozó Makefile állományokban szereplő make utasításokat, valamint a hivatkozott doc.project.mk vázlatos felépítését; további make változókon és célokon keresztül miként tudjuk testreszabni a dokumentáció különböző változatainak előállítási folyamatát. Munkánk folyamán az itt felsorolt eszközök állnak rendelkezésünkre. Használjuk ki az általuk nyújtott lehetőségeket, amennyire csak tudjuk. Az elsődleges eszköz maga a make parancs, pontosabban a Berkeley Make. Csomagokat a &os; alaprendszerében megtalálható pkg_create programmal tudunk készíteni. Ha nem &os; alatt dolgozunk, akkor vagy csomagok nélkül kell dolgoznunk, vagy magunknak kell ezeket elkészítenünk. A gzip segítségével lehet az előállított dokumentumok tömörített változatát elkészíteni. Emellett még a bzip2 és zip típusú tömörítés is támogatott. A tar programot is támogatjuk, a csomagok készítéséhez kell. A dokumentáció telepítésének elfogadott eszköze az install program. Természetesen léteznek egyéb megoldások is. Nem valószínű, hogy ez az utolsó két eszközt ne lenne elérhető a rendszerünkön, csupán a teljesség kedvéért említettük meg ezeket. A &os; Dokumentációs Projekt által használt könyvtárakban megtalálható Makefile állományoknak három típusa létezik: Az alkönyvtári Makefile állományok egyszerűen csak továbbadják a parancsokat az alkönyvtáraiknak. A dokumentumokra vonatkozó Makefile állományok írják le, hogy milyen dokumentumokat kellene az adott könyvtárban előállítani. Az .mk állományok segítik valamilyen formában a dokumentumok előállítását. Többnyire doc.xxx.mk névvel láthatóak. Ezek a típusú Makefile állományok általában a következő alakúak: SUBDIR =articles SUBDIR+=books COMPAT_SYMLINK = en DOC_PREFIX?= ${.CURDIR}/.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" Röviden összefoglalva: az első négy nem üres sorban ún. make változókat definiálunk. Ezek rendre a SUBDIR, COMPAT_SYMLINK és DOC_PREFIX. Az első SUBDIR sornál, illetve a COMPAT_SYMLINK sorában láthatjuk hogyan kell egy új értéket beállítani egy ilyen változónak. A második SUBDIR sorban azt láthatjuk, hogyan tudunk a változó aktuális értékéhez továbbiakat hozzáfűzni. Ebben az esetben tehát az utasítás végrehajtása után a SUBDIR értéke articles books lesz. A DOC_PREFIX esetében pedig olyan értékadást figyelhetünk meg, amelyik csak akkor hajtódik végre ténylegesen, ha a változónak addig még nem volt értéke. Ez olyankor tud kapóra jönni, amikor a DOC_PREFIX nem pontosan az, amire a Makefile számít — a felhasználó ekkor meg tudja adni a helyes értéket. Ez így együttesen tehát mit is jelent? A SUBDIR összefoglalja azokat a könyvtárakat, amelyekben a dokumentumok előállításának folyamatának folytatódnia kell majd. A COMPAT_SYMLINK a kompatibilitás céljából létrehozott szimbolikus linkekre vonatkozik, amelyek (valamilyen csoda folytán) az adott nyelv hivatalos kódolására mutatnak (tehát például a doc/en a en_US.ISO8859-1 könyvtárra). A DOC_PREFIX a &os; Dokumentációs Projekt főkönyvtárához vezető utat adja meg. Ezt nem mindig egyszerű megtalálni, ezért a rugalmasság kedvéért könnyedén felül is definiálható. A .CURDIR a make egyik saját belső változója, amelyben az aktuális könyvtár elérési útját tárolja. Végül az utolsó sorban a &os; Dokumentációs Projekt összes Makefile állományára vonatkozó, rendszerszintű doc.project.mk állományra hivatkozunk, amelyen keresztül az iménti változókból épül fel a dokumentumok előállításának pontos menete. Ezekben a Makefile állományokban az adott könyvtárban található dokumentumok előállítását leíró különböző make változók szerepelnek. Lássunk erre egy példát: MAINTAINER=pgj@FreeBSD.org DOC?= book FORMATS?= html-split html INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= # Az SGML forrás SRCS= book.xml DOC_PREFIX?= ${.CURDIR}/../../.. .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk" A MAINTAINER változó nagyon fontos. A &os; Dokumentációs Projekten belül ezen a változón keresztül jelezhetjük a dokumentum birtoklását, vagyis karbantartási kötelezettségünket. A DOC hivatkozik (az .xml kiterjesztés nélkül) az adott könyvtárban található dokumentum fő forrására. Emellett az SRCS változóban kell összefoglalnunk a dokumentumot alkotó források neveit. Ebben érdemes megadni minden olyan állományt, amelynek megváltozása esetén újra elő kell állítani az érintett dokumentumot. A FORMATS segítségével definiáljuk a dokumentum alapértelmezetten előállítandó formátumait. A INSTALL_COMPRESSED változóban a dokumentum elkészítésekor felhasználandó tömörítési formákat adhatjuk meg. A INSTALL_ONLY_COMPRESSED változó alapból üres, de ha adunk neki valamilyen egyéb értéket, akkor a dokumentumoknak csak a tömörített változata fog elkészülni. A változók feltételes értékadásáról már volt szó az előző szakaszban. A DOC_PREFIX változó és az .include utasítás a korábbiak alapján már ismerős lehet. Ezek az állományok legjobban talán önmagukon keresztül mutathatóak be. A következő rendszerszintű .mk állományokat használjuk a &os; Dokumentációs Projektben: A doc.project.mk a központi .mk állomány, amely szükség szerint hivatkozik az összes többi .mk állományra. Az előállítás és a telepítés során a doc.subdir.mk felelős a dokumentumokat tároló könyvtárak bejárásért. A doc.install.mk tartalmazza a karbantartóval és a telepítéssel kapcsolatos változókat. A doc.docbook.mk állomány csak akkor kerül feldolgozásra, ha a DOCFORMAT értéke docbook és a DOC változónak van értéke. Nézzünk bele: DOCFORMAT?= docbook MAINTAINER?= doc@FreeBSD.org PREFIX?= /usr/local PRI_LANG?= en_US.ISO8859-1 .if defined(DOC) .if ${DOCFORMAT} == "docbook" .include "doc.docbook.mk" .endif .endif .include "doc.subdir.mk" .include "doc.install.mk" Ha nem állítjuk be a dokumentum Makefile állományában, akkor a DOCFORMAT és a MAINTAINER változók ezen a helyen kapnak értéket. A PREFIX adja azt a könyvtárat, amelyen belül elérhetőek a dokumentáció előállításához szükséges eszközök. A csomagok és portok átlagos használata esetén ez a /usr/local. A PRI_LANG adja meg azt a nyelvet és kódolást, amely a dokumentációt olvasó felhasználó számára elsődlegesként leginkább elfogadott. Alapértelmezés szerint ez az amerikai angol. A PRI_LANG változó semmilyen hatással nincs a dokumentumok előállítására. Egyedül a &os; dokumentáció telepítésekor a leggyakrabban hivatkozott dokumentumokhoz létrehozandó szimbolikus linkek készítésénel van szerepe. A .if defined(DOC) sorban a Makefile állományokban megadható elágazásokra láthatunk példát. Hasonlóan más programokhoz, a Makefile működését tudjuk meghatározni egy logikai kifejezés igazságértéktől függően. Ebben a kifejezésben a defined függvény, amely megadja, hogy a paramétereként megadott változó definiált-e. A következő elágazásban, vagyis az .if ${DOCFORMAT} == "docbook" utasításban azt vizsgáljuk meg, hogy a DOCFORMAT változó értéke "docbook" vagy sem. Amennyiben a válasz erre igen (vagyis igaz), beemeljük a doc.docbook.mk tartalmát. Az előbb említett két elágazást rendre az .endif kulcsszóval zárjuk le. Ez az állomány már túlságosan nagy ahhoz, hogy a fejezeten belül könnyen ki lehessen elemezni. Ezért az előző szakaszok alapján a részleteket a kedves Olvasóra bízzuk, ehhez adunk még itt némi segítséget. A SUBDIR tartalmazza azokat az alkönyvtárakat, amelyeket a feldolgozás során be kell járnunk. A ROOT_SYMLINKS a dokumentáció főkönyvtárából szimbolikusan linkelendő könyvtárak neveit adja meg, amennyiben az adott nyelv (a PRI_LANG változó szerint) az elsődleges. A COMPAT_SYMLINK változót már korábban bemutattuk az alkönyvtári Makefile állományok című szakaszban. A függőségi viszonyokat cél: függőség1 függőség2 ... formában írjuk fel, ahol így megmondjuk, hogy a cél létrehozásához először milyen elemeknek kell létezniük. Ezeket nevezzük függőségeknek. A függőségi viszony megadása alatt lehetőségünk van részletezni a függőségekből a cél előállításához szükséges utasításokat. Ezt akkor kell megtenni, ha a cél és a függőségek közti átalakítást előzőleg még nem definiáltuk, vagy ha az adott esetben az átalakítás eltér a korábbiaktól. A .USE nevű speciális függőség egy makróval egyenértékű eszköz használatára ad lehetőséget. _SUBDIRUSE: .USE .for entry in ${SUBDIR} @${ECHO} "===> ${DIRPRFX}${entry}" @(cd ${.CURDIR}/${entry} && \ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) .endfor A fenti kódrészletben tehát a _SUBDIRUSE most már egy makró lesz, amely ha megjelenik a függőségek között, akkor a törzsében megadott parancsokat hajtja végre. Mi különbözteti meg ezt a makrót a többi céltól? Két lényeges eltérés: először is, a benne megadott utasítások a rá függőségként hivatkozó célhoz társított átalakítást végző utasítások után fognak lefutni, másrészt nem befolyásolja a jelenleg feldolgozás alatt álló cél nevét tároló .TARGET változó értékét. clean: _SUBDIRUSE rm -f ${CLEANFILES} Ebben a kódrészletben a tehát clean esetében csak az rm -r ${CLEANFILES} parancs lefutása után fog végrehajtódni a _SUBDIRUSE makró tartalma. Ennek hatására a clean megy egyre lentebb és lentebb a könyvtárszerkezetben, miközben törli a előzőleg előállított állományokat. Az install és a package célok egyaránt folyamatosan haladnak lefelé a könyvtárszerkezetben és az alkönyvtárakban hívják saját maguk tényleges változatát (ezek a realinstall és realpackage). A clean eltávolítja a folyamat során keletkezett állományokat (és az előbbiekhez hasonlóan lefele halad a könyvtárszerkezetben). A cleandir ugyanezt csinálja, de ha talál a tárgykódokhoz tartozó könyvtárat, akkor azt is törli. Az exists egy másik logikai függvény, amellyel lekérdezhetjük, hogy a paramétereként megadott állomány létezik-e. Az empty logikai függvény igaz értékű, ha a paramétereként megadott változó értéke üres. A target logikai függvény igaz értékű, ha a paraméterként megadott cél még nem létezik. A .for utasítás segítségével adott utasításokat tudunk elvégezni egy változó tartalmaként megadott, szóközökkel határolt elemekre. A ciklus belsejében egy változóból érhetjük el az aktuálisan feldolgozott elemet. _SUBDIRUSE: .USE .for entry in ${SUBDIR} @${ECHO} "===> ${DIRPRFX}${entry}" @(cd ${.CURDIR}/${entry} && \ ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) .endfor A fenti kódrészletben ha a SUBDIR üres, akkor nem történik semmi. Ha viszont egy vagy több elemet is tartalmaz, akkor a .for és az .endfor között megadott utasítások megismétlődnek minden egyes elem esetén. Ezek értékét a ciklus belsejében rendre a entry változóban veszi fel.