6.3. Az egyes dokumentumokkal kapcsolatos tudnivalók

Ebben a szakaszban a FreeBSD Dokumentációs Projekt keretein belül gondozott különböző dokumentumokat ismerhetjük meg részletesebben.

6.3.1. A kézikönyv

books/handbook/

A kézikönyv a FreeBSD kiterjesztéseit tartalmazó DocBook DTD szerint készült.

A kézikönyv a DocBook book elemének megfelelően szerveződik. Több part elemmel jelölt részből áll, amelyek mindegyike több chapter elemmel jelölt fejezetet foglal magában. Ezek a fejezetek további szakaszokra (sect1) bomlanak, amelyek helyenként alszakaszokra (sect2, sect3) oszlanak, és így tovább.

6.3.1.1. Fizikai szervezés

A kézikönyv forrásai több különböző állományban és könyvtárban a handbook könyvtáron belül találhatóak.

Megjegyzés:

A kézikönyv szervezése időről-időre változik, ezért könnyen előfordulhat, hogy ez a dokumentum csak kissé késve követi ezeket a változtatásokat. Ha további kérdéseink lennének a kézikönyv szervezéséről, bátran írjunk a FreeBSD Dokumentációs Projekt levelezési lista címére!

6.3.1.1.1. Makefile

A Makefile állományban definiálódnak olyan változók, amelyek a SGML források különböző formátumúra alakításának menetét befolyásolják, illetve hivatkozik a kézikönyv forrásaira. Ezután beemeli a doc.project.mk állományt, és így lényegében betölti a dokumentumok átalakításáért felelős további utasításokat.

6.3.1.1.2. book.xml

Ez a kézikönyv legfelső szintű dokumentuma. Ebben van a kézikönyv dokumentípus-deklarációja, illetve a szerkezetét leíró további elemek.

A book.xml az .ent kiterjesztésű állományokat paraméteregyedek segítségével tölti be. Ezek az állományok (amelyekről később még szó lesz) aztán a kézikönyv további részeiben használt általános egyedeket definiálnak.

6.3.1.1.3. könyvtár/chapter.xml

A kézikönyv egyes fejezetei egymástól különálló könyvtárakban, chapter.xml nevű állományokban tárolódnak. Ezeket a könyvtárakat az adott fejezetet jelölő chapter id tulajdonsága szerint szokták elnevezni.

Például ha az egyik fejezet forrásában a következő sor olvasható:

<chapter id="kernelconfig">
...
</chapter>

Ekkor a chapter.xml nevű állományt tartalmazó könyvtár neve kernelconfig lesz. Egy ilyen állomány általában a teljes fejezetet tartalmazza.

A kézikönyv HTML változatának készítése során ebből a kernelconfig.html állomány fog keletkezni. Ezt azonban az id értéke határozza meg, semmi köze nincs a könyvtár elnevezéséhez.

A kézikönyv korábbi változataiban az összes forrás a book.xml állománnyal volt egy szinten, és az adott chapter elemek id tulajdonságának megfelelően került elnevezésre. Az egyes fejezetekhez most már külön-külön tudunk képeket csatolni, amelyeket a fejezeteknek megfelelő könyvtárban kell elhelyezni a share/images/books/handbook könyvtáron belül. Ha honosítani akarjuk a képeket, akkor viszont ügyeljünk arra, hogy az adott fejezet könyvtárába, az SGML források mellé tegyük a lefordított képeket. A névütközés egy idő után úgyis elkerülhetetlenné válik, és sok, kevés állományt tartalmazó könyvtárral egyébként is könnyebb dolgozni, mint egy sok állományt tartalmazó könyvtárral.

A kézikönyv forrásaiban könnyen láthatjuk, hogy sok ilyen könyvtár van, bennük egy-egy chapter.xml állománnyal. Például basics/chapter.xml, introduction/chapter.xml és printing/chapter.xml.

Fontos:

A fejezeteket és könyvtárakat nem szabad semmilyen sorrendiségre utaló módon elnevezni. A fejezetek elrendezése ugyanis változhat a kézikönyv egy esetleges átszervezése során. Az ilyen átszervezések során pedig (általában) nem lenne szabad állományokat átnevezni (hacsak komplett fejezeteket nem mozgatunk fentebb vagy lentebb a szerkezetben).

Az egyes chapter.xml állományok önmagukban teljes SGML dokumentumok. Különösen azért, mert semmilyen DOCTYPE sor nem található az elejükön.

Ez abból a szempontból hátrányos, hogy ezeket az állományokat ezért nem tudjuk normál SGML állományokként kezelni. Emiatt ezeket nem lehet egyszerűen, a kézikönyvhöz hasonlóan módon HTML, RTF, PS vagy más egyéb formátumba átalakítani. Ezért tehát könnyen előfordulhat, hogy a fejezetek megváltoztatásakor a teljes kézikönyvet elő kell állítanunk.

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