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ő

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

Előző | Tartalom | Következő
A ``nyelv`.`kódolás`/` könyvtárak | Fel | A dokumentáció előállításának folyamata

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