| A FreeBSD Dokumentációs Projekt irányelvei kezdőknek | ||
|---|---|---|
| Előző | Fejezet 6. A dokumentumok szervezése a doc/ könyvtáron belül | Következő |
Ebben a szakaszban a FreeBSD Dokumentációs Projekt keretein belül gondozott különböző dokumentumokat ismerhetjük meg részletesebben.
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.
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!
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.
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.
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): <freebsd-questions@FreeBSD.org>.
Ha ezzel a dokumentummal kapcsolatban van kérdése,
kérjük erre a címre írjon: <gabor@FreeBSD.org>.