Gentoo XML Útmutató

1.  Az alapok

A Guide XML tervezési céljai

Az útmutató típusú dokumentumok XML szabályai egyszerűek, ugyanakkor hatékonyak, így könnyű megtanulni, mégis minden eszközt a kezünkbe ad, hogy webes irományokat hozzunk létre. A felhasználható elemek számát igyekeztünk minimumra szorítani, csak a legszükségesebbek maradtak meg. Ezért az útmutatókat egyszerűen át lehet ültetni más formátumokba, például DocBook XML/SGML-be, vagy webes HTML-be.

A fő cél az volt, hogy az útmutatók XML dokumentumait könnyű legyen létrehozni és átalakítani.

További információk

Ha az a terved, hogy dokumentációt készíts a Gentoo számára, vagy csak ki akarod próbálni a GuideXML-t, olvasd el a Dokumentációs Tippek és Trükkök útmutatót! Ebben (meglepő módon :) ) rengeteg tippet, trükköt találsz, hogyan kell dokumentumokat fejleszteni.

Ugyancsak hasznos lehet olvasás közben ennek a dokumentumnak az XML forráslistáját is böngészgetni.

2.  Guide XML

Alapvető felépítés

No, akkor kezdjük el megtanulni a GuideXML szabályait! Indítsunk a dokumentumok kezdő tagjeivel:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide link="/doc/hu/guide.xml" lang="hu">
<title>Gentoo Dokumentációs Útmutató</title>

<author title="Szerző">
  <mail link="név@gentoo.org">Szerző Neve</mail>
</author>

<abstract>
Az alábbi útmutató megmutatja, hogyan hozhatunk webes dokumentumokat
az új, egyszerűsített Gentoo GuideXML szabályainak felhasználásával.
Ez egyben a teljes Gentoo dokumentáció hivatalos formátuma is, ez a leírás is GuideXML-el
készült.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1.0</version>
<date>2004-12-25</date>

Az első sorokban a kötelezően megadandó tagek szerepelnek, ezek azonosítják a dokumentumot XML-nek, és megadják a DTD-jét. A <!-- $Header$ --> sort a CVS kiszolgáló automatikusan módosítja, így könnyebb a különféle verziók nyomonkövetése. Ez után a <guide> áll -- az egész útmutató típusú dokumentum egy <guide> </guide> tagpárosba van ágyazva. A link paramétert kötelező megadni, lehetőleg a dokumentum abszolút elérési útját kell tartalmaznia (a dokumentumgyökérhez képest). Sokszor azonban elég, ha csak az állomány nevét írod bele. Ez alapján készül el a dokumentum nyomtatásra szánt változatára mutató hivatkozás. Ha rossz értéket adsz meg, a hivatkozás vagy nem fog működni, vagy rossz dokumentumra mutat. A lefordított dokumentumokban kötelező megadni a teljes útvonalat, mert ez alapján ellenőrizhető, hogy az eredetiből van-e újabb verzió. A lang paraméterrel a dokumentum nyelvi kódját lehet megadni. Ez a dátumok formázására, valamint egyes szövegek, mint pl. "Note", "Content", stb. nyelvhelyes megjelenítésére való, értéke alaphelyzetben az angol.

A következő <title> tag között az útmutató típusú dokumentum címe szerepel.

Elérkeztünk az <author> tagig, melyek a dokumentum kölönféle szerzőinek adatait tartalmazzák. Mindegyik <author> tagnek lehet egy opcionális title paramétere, itt adható meg, hogy az adott szerző pontosan kicsoda (szerző, segédszerző, szerkesztő, stb.). Jelen példánkban a nevet egy másik tagbe is belefoglaltuk - a <mail> az adott személy email-címét adja meg. A <mail> taget nem kötelező megadni, az <author>-ból pedig legalább egynek szerepelnie kell egy útmutatóban.

Az <abstract>, <version> és <date> tagek a dokumentum rövid összefoglalóját, verzióját, és a verzió készültének dátumát (ÉÉÉÉ-HH-NN formában) tartalmazzák. A hibás vagy nem ÉÉÉÉ-HH-NN formátumú dátumok a kész dokumentumban formázatlanul jelennek meg (ahogyan be lettek írva).

Készen is vagyunk az útmutatók kezdő tagjeivel. A <title> és a <mail> kivételével ezek sehol máshol nem szerepelhetnek, csak közvetlenül a <guide> tagben. A következetesség miatt ajánlott (bár nem kötelező) még a dokumentum tartalma előtt megadni őket.

Végül szerepel még egy <license/> tag is, amely arra való, hogy a Dokumentációs irányelv-ben meghatározott Creative Commons - Attribution / Share Alike licensz alatt publikáljuk írásunkat.

Fejezetek és szakaszok

Miután sikeresen megadtuk a kezdő tageket, itt az idő, hogy a dokumentum szerkezeti elemei is a helyükre kerüljenek. Az útmutató típusú dokumentumok fejezetekre tagolódnak, a fejezetek egy vagy több szakaszból állnak. Minden fejezetnek, szakasznak van címe. Következzen egy példafejezet, ami egyetlen szakaszból, az pedig egy bekezdésből áll. Ha ezt az XML kódot az előző példa után másolod, és a végére egy </guide> taget teszel, készen is van az első (bár nem túl nagy) útmutató- dokumentumod:

<chapter>
<title>Ez a fejezet</title>
<section>
<title>Ez a fejezet első szakasza</title>
<body>

<p>
Ez a szakasz szövege.
</p>

</body>
</section>
</chapter>

A fejezet címét a <chapter> elembe rakott <title> gyermek- elemmel adtam meg. Ezután a <section> elemmel létrehoztam egy szakaszt. Láthatod, hogy ennek a <section>-nek két gyerek-eleme van: egy <title> és egy <body>. A <title> már ismerős, a <body> azonban nem -- ebben helyezkedik el a szakasz szövege. Most pedig lássuk, milyen tageket lehet használni a <body> elemen belül!

Hogyan néz ki a <body>?

Ideje megismerni, hogyan is épül fel maga a dokumentum. Lássunk egy példát, hogyan néz ki XML-kódban a <body> elem:

<p>
Ez egy bekezdés.  A <path>/etc/passwd</path> egy állomány.
A <uri>http://forums.gentoo.org</uri> a kedvenc weboldalam.
Ha akarod, írd be az <c>ls</c> parancsot.  Most már <e>tényleg</e> 
le akarok feküdni!
</p>

<pre caption="Példakód">
Ez egy szöveges kimenet, vagy kód.
# <i>ezt a felhasználó gépeli be</i>

Sokkal könnyebb a HTML/XML kódot olvasni, ha a kijelöléseket kiemeled:
<izé><i>aha</i></izé>

<comment>(Így kell megjegyzést szúrni kódblokkba)</comment>
</pre>

<note>
Ez egy megjegyzés.
</note>

<warn>
Ez egy figyelmeztetés.
</warn>

<impo>
Ez fontos.
</impo>

A fenti <body> elem a következőképpen néz ki feldolgozás után:

Ez egy bekezdés. A /etc/passwd egy állomány. A http:// forums.gentoo.org a kedvenc weboldalam. Ha akarod, írd be az ls parancsot. Most már tényleg le akarok feküdni!

Ez egy szöveges kimenet, vagy kód.
# ezt a felhasználó gépeli be

Sokkal könnyebb a HTML/XML kódot olvasni, ha a kijelöléseket kiemeled:
<izé>aha</izé>

(Így kell megjegyzést szúrni kódblokkba)

A <body> tagjei

Az előző szakaszban jó sok új taget mutattunk be -- ideje szót ejteni róluk. A <p> (bekezdés), <pre> (kód), <note> (megjegyzés), <warn> (figyelmeztetés) és <impo> (fontos) tagek egy vagy több sornyi szöveget tartalmazhatnak. A <table>, <ul>, <ol> és <dl> elemek mellett (melyekről később lesz szó) csak ezek a tagek lehetnek közvetlenül a <body>-ban. Ja, és még valami: ezeket a tageket nem szabad egymásba ágyazni! Magyarul, egy <p> elembe ne tegyél <note>-ot! Gondolom, már rájöttél, hogy a <pre> elemben a (puha) szóközök változtatás nélkül jelennek meg, úgyhogy nyugodtan használható programkódok beírására. Ennek a tagnek nevet is kell adnod a caption paraméterrel:

<pre caption="Az uptime kimenete">
# <i>uptime</i>
16:50:47 up 164 days,  2:06,  5 users,  load average: 0.23, 0.20, 0.25
</pre>

Mottók

Az eredeti 13 állam küldöttei alkotják a teljes Kongresszust. A Függetlenségi Nyilatkozatot ketten, mégpedig Thomas Jefferson, egy szűz és Benjamin Franklin írták alá. Franklin úgy fedezte fel az elektromosságot, hogy két macskát dörzsölt egymáshoz, majd kijelentette: "A félbevágott ló nem tud állni." Franklin végül 1790-ben halt meg, és azóta is halott.

—ismeretlen tanuló

A mottókat többnyire a fejezetek elején használjuk, azok rövid összefoglalására. Egy egyszerű bekezdéstől csak a by paraméterben tér el, ebben kell megadni az aláírást.

<p by="ismeretlen tanuló">
Az eredeti 13 állam küldöttei alkotják a...
</p>

<path>, <c>, <b>, <e>, <sub> és <sup>

A <path>, <c>, <b>, <e>, <sub> és <sup> elemek bármelyik gyerek-<body> tagben szerepelhetnek, kivéve a <pre> taget.

A <path> elem olyan szöveget jelöl, amely egy lemezen lévő állományra mutat -- értéke lehet abszolút vagy relatív útvonal, vagy akár egy egyszerű állománynév is. Ez az elem többnyire monospace karakterrel (minden betű ugyanolyan széles) lesz kiírva, hogy könnyebb legyen megkülönböztetni a normál bekezdés-szövegtől.

A <c> elemmel parancsot vagy felhasználó által begépelendő szöveget jelölünk. Mondhatni, ezzel keltjük fel az olvasó figyelmét, hogy most gépelnie kell, ami valamit csinálni fog. Ebben a dokumentumban például az összes XML tag a <c> elemen belül szerepel, mert ez olyasvalami, amit a felhasználó begépelhet, és nem elérési út. Így sokkal könnyebben lehet megtalálni a kipróbálható parancsokat. Mivel a <c> elem már eleve eltér a normál szövegtől, a felhasználó által begépelendő szöveget nem szükséges idézőjelbe tenni. Vagyis például ne hivatkozz a "<c>" elemre, mint ahogy most én tettem... A felesleges idézőjelek mellőzése nem csak olvashatóbbá, de szebbé is teszi a dokumentumot!

Gondolom, már kitaláltad, hogy a <b> használatával félkövér karaktereket lehet beírni.

Az <e> arra való, hogy kiemelj valamit (szót, kifejezést) a szövegből, például: Most már tényleg több pontosvesszőt kellene használnom. Láthatod, az adott rész eltér, kiemelődik a bekezdés normál szövegéből. Ezzel a szövegedbe sokkal több erőt tudsz vinni!

A <sub> és <sup> elemek _{alsó index} és ^{felső index} beírására valók.

Példakódok és színek

Ahhoz, hogy a kódpéldák olvashatóbbak legyenek, a <pre> blokkokban a következő tageket érdemes használnod:

<i>

A felhasználó által beírt adatokat emeli ki a megjelenített szövegben

<comment>

Megjegyzés, az ebben foglaltak az utána álló parancs(ok)ról ad bővebb információt

<keyword>

A példakódban használt (program)nyelvben használt kulcsszavakat jelöli meg

<ident>

Azonosítókat lehet vele megjelölni

<const>

Konstansokat lehet vele megjelölni

<stmt>

Kifejezéseket lehet vele megjelölni

<var>

Változókat lehet vele megjerlölni

Egy példa a <pre> blokkban használható színekkel:

# Copyright 1999-2006 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
HOMEPAGE="http://ctags.sourceforge.net"
SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz"


LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~mips ~sparc ~x86"
IUSE=""

src_compile() {
    econf --with-posix-regex || die "econf failed"
    emake || die "emake failed"
}

src_install() {
    make DESTDIR="${D}" install || die "install failed"

    dodoc FAQ NEWS README
    dohtml EXTENDING.html ctags.html
}

A <mail> és <uri> használata

Korábban már láttuk, hogyan használhatjuk a <mail> taget; segítségével az adott szöveget email-címre mutató linkké alakíthatjuk, pl. <mail link="foo@bar.com">Mr. Foo Bar</mail> Ha csak az email-címet akarod kiíratni, a <mail>foo@bar.com</mail> alakot kell használnod, ami így fog kinézni: foo@bar.com.

Az <uri> tag Internetes tartalmak megjelölésére szolgál. Két alakja van -- az első arra való, hogy folyó szövegben írasd ki az adott URI-t, pl. http://forums.gentoo.org. Ahhoz, hogy ezt a linket létrehozzam, a következőt kellett begépelnem: <uri>http://forums.gentoo.org</uri>. A másik alak ahhoz kell, ha valamely szöveget akarsz linkké alakítani, pl. a Gentoo fórum. Ehhez pedig a következő kód kell: <uri link="http://forums.gentoo.org">a Gentoo fórum</uri>. Ha a Gentoo weboldalait akarod linkelni, nem szükséges a teljes http://www.gentoo.org/ címet beírnod: a dokumentációk főoldalához elég ennyit írnod: <uri link="/doc/en/index.xml">dokumentációk főoldala</uri>. Ha egy könyvtár indexére hivatkozol, akár az index.xml-t is kihagyhatod, elég a <uri link="/doc/en/">dokumentációk főoldala</uri> forma is.

Ábrák

Így tudsz ábrákat beszúrni a dokumentumba: <figure link="mygfx.png" short="képem" caption="a kedvenc képem"/>. A link paraméter mutat a képre, a short egy rövid leírást tartalmaz (jelenleg a kép HTML kódjának alt paraméterét adja meg), majd a felirat következik. Nem valami bonyolult. :) Az eredeti HTML-formát is használhatod: az <img src="foo.gif"/> tag mindenféle felirat, keret, stb. nélkül szúrja be a képet.

Táblázatok

A HTML-hez hasonló, de egyszerűsített formájú táblázatot is használhatsz a <table> taggel. Sorokat a <tr>-el kezdhetsz, de vigyázz, a HTML-ből megszokott <td> taget nem használhatod adatbevitelre! Erre a <th> való fejléc, és a <ti> normál, általános adat beírására. A <th> taget akárhol használhatod, ahol a <ti> is állhat -- nincs olyan korlátozás, hogy a <th> elem csak az első sorban lehet.

Ezen kívül a tábla fejlécei (<th>) és elemei (<ti>) ismerik a colspan és rowspan paramétereket, melyekkel több sort, oszlopot, vagy akár mindkettőt összefoghatsz.

Csinosításképpen a tábla elemeit (<ti>) jobbra vagy középre igazíthatod az align paraméterrel. A tábla fejlécei (<th>) automatikusan középre lesznek igazítva.

Felsorolások

Számozott vagy számozatlan felsorolásokhoz az XHTML-ből ismert <ol>, <ul> és <li> tageket használhatod. Csak a <body> és a <li> tageken belül állhatnak, vagyis egymásba ágyazott listákat is készíthetsz. Azt azonban ne feledd, hogy XML-ről van szó, nem pedig HTML-ről, így minden taget le kell zárnod, még a lista elemeit is!

Definíciós listák (<dl>) is létrehozhatók. Ebben az esetben sem a definíció leíró tagje (<dt>), sem a definíció adat-tagje (<dd>) nem tartalmazhat blokkleíró tageket, mint pl. bekezdések vagy figyelmeztetések. Egy definíciós lista kinézete:

<dl>

Egy Definíciós Lista tag tartalma

<dt>

Definíciós Term (leíró) tagek

<dd>

és Definíciós Data (adat) tagek

A következő, w3.org címről kimásolt felsorolásban a definíciós lista számozott és számozatlan listákat is tartalmaz. Ugyanakkor más definíciós listát nem tartalmazhat!

Hozzávalók:

• 100 g. liszt
• 10 g. cukor
• 1 csésze víz
• 2 tojás
• só, bors

Elkészítés:

1. A száraz összetevőket alaposan keverjük össze!
2. Öntsük bele a vizet és a tojást!
3. 10 percig kevergessük!
4. 300 fokos sütőben 1 órán át süssük!

Megjegyzés:

Sokkal finomabb lesz, ha mazsolát is teszünk bele!

Dokumentumon belüli hivatkozások

Hivatkozások segítségével a dokumentum egyes részeire is hivatkozhatunk. Az első fejezetre mutató linket a <uri link="#doc_chap1">első fejezet</uri> kóddal hozhatod létre. Az első fejezet második szakaszára pedig az <uri link="#doc_chap1_sect2">első fejezet második szakasza</uri> alakban hivatkozhatsz. Az első fejezet hármas ábráját az <uri link="#doc_chap1_fig3">1.3. ábra</uri> alakban érheted el. De megnézheted a második fejezet kettes kódlistáját is a <uri link="#doc_chap2_pre2">2.2. kódlista</uri> segítségével.

Némelyik útmutató sűrűn változik, ezért az ilyesfajta számozás később rossz hivatkozásokat eredményezhet. Ha ezt el akarod kerülni, adj nevet a kívánt <chapter>, <section> vagy <tr> tagnek. Ezt az id paraméterrel teheted meg, később erre tudsz hivatkozni:

<chapter id="blabla">
<title>Ez egy blabla!</title>
...
<p>
Erről több információt olvashatsz a <uri link="#blabla">blabla fejezetben</uri>
</p>

Nem hivatalos és elavult dokumentumok

A disclaimer paraméterrel régebbi, elavult útmutatókhoz, cikkekhez, kézikönyvekhez rendelhetünk egy olyan előre megadott leírást, mely a szöveg elején jelenik majd meg. A következőket használhatod:

• az articles paraméter nem a Gentoo közösség által írt újraközölt cikkekhez
• a draft olyan dokumentumot jelöl, mely még fejlesztés alatt áll, így nem tekinthető végleges, hivatalos változatnak
• az oldbook régi kézikönyvekhez kell, ezeket már senki sem tartja karban
• az obsolete jelöli az elavult, megszűnt dokumentumokat.

Ha egy dokumentumot elavultnak jelölsz, érdemes megadni az új verziójára mutató hivatkozást. A redirect paraméter pont erre való: az olvasót automatikusan az új oldalra próbálja átirányítani - de ez nem minden esetben működik.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide link="/doc/en/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml">
<title>Gentoo x86 Telepítési Útmutató</title>

<author title="Szerző">
...

3.  Kódformázási szabályok

Bevezetés

Mivel minden Gentoo dokumentáció közös munka eredménye, és valószínűleg sok ember fogja módosítgatni, be kell tartani pár kódolási formát. Ennek két része van. Az első a belső kódolás - hogyan kell elhelyezni az XML tageket. A második a tartalmi forma - hogy ne zavarjuk össze az olvasót.

A két szakasz bővebb kifejtése alább olvasható.

Belső kódolási szabályok

Minden GuideXML tag után (a nyitó és záró tag után is) egyből új sort kell elhelyezni, kivéve a <version>, <date>, <title>, <th>, <ti>, <li>, <i>, <e>, <uri>, <path>, <b>, <c>, <comment> és <mail> tageket.

Üres sort kell elhelyezni minden nyitó <body> tag után, és minden <chapter>, <p>, <table>, <author>, <pre>, <ul>, <ol>, <warn>, <note> és <impo> nyitó tag elé.

A sorok hosszát 80 karakterben kell korlátozni sortördelés segítségével, kivéve a <pre> tagen belül. Csak akkor térhetsz el ettől, ha nincs más megoldás, pl. egy hivatkozás túllépi ennek hosszát. Ekkor a szerkesztő feladata, hogy az első lehetséges szóköznél tördeljen. A <pre> elemben lévő formázott tartalmat próbáld meg 80 oszlopon belül tartani, a konzolos felhasználók életét megkönnyítendő.

A beljebb szedés nem használható, kivéve az olyan XML szerkezeteknél, ahol a szülő tag <tr> (a <table> tagen belül), <ul>, <ol>, <dl> vagy <author>. A szöveg beljebb szedéséhez csak két szóközt használhatsz. Vagyis nem tabulátort és nem több szóközt. Tabulátort egyébként sem lehet GuideXML dokumentumokban használni.

Ha <ti>, <th>, <li> vagy <dd> szerkezeteken belül fordulna elő sortördelés, beljebb kell szedned a tartalmat.

A beljebb szedésre lássunk egy példát:

<table>
<tr>
  <th>Izé</th>
  <th>Bizé</th>
</tr>
<tr>
  <ti>Íme, egy beljebb szedett szöveg.</ti>
  <ti>
    Ha a szöveg nem fér el egy 80 karakter hosszú sorban, mindenképpen
    beljebb kell szedned, ha a szülő tag megengedi.
  </ti>
</tr>
</table>

<ul>
  <li>Első lehetőség</li>
  <li>Második lehetőség</li>
</ul>

A paraméterek esetén nem állhat szóköz a paraméter, az "=" jel és a paraméter értéke között. Például:

Rossz :     <pre caption = "paraméterek">
Helyes:     <pre caption="paraméterek">

Külső kódolási szabályok

Táblázatokon (<table>), felsorolásokon (<ul>, <ol>) és a <dl> tagen belül a mondatok végén nem szabad használni pontot ("."), csak ha a szöveg több mondatból áll. Ebben az esetben azonban minden mondat végére pontot (vagy egyéb írásjelet) kell tenni.

Minden mondatot, még a táblázatokon és felsorolásokon belül is, nagybetűvel kell kezdeni.

<ul>
  <li>Nem kell pont</li>
  <li>Ide viszont kell pont. Több mondat, emlékszel?</li>
</ul>

A kódlistáknak mindig lennie kell egy caption paraméterének!

Ha lehet, törekedj arra, hogy az <uri> taget minél többször használd a link paraméterrel. Más szóval, a Gentoo fórumok forma jobb, mint ez: http://forums.gentoo.org.

Ha megjegyzést fűzöl valamihez egy <pre> szerkezeten belül, használd a <comment> taget és zárójeleket, vagy pedig az adott (program)nyelv saját megjegyzés-jelét (# jelet bash szkriptek, stb. esetén, // jelet C kód esetén, stb.). A megjegyzést a leírandó szöveg elé tedd!

(a "john" helyére a saját felhasználói nevedet írd)
# id john

4.  Kézikönyv-formátum

Útmutató vs Könyv

Nagyméretű dokumentációk esetén, mint amilyen pl. a Telepítési utasítások , más formátumra volt szükség. Ezért kifejlesztettünk egy GuideXML- kompatibilis bővítést, mellyel több részből álló, többoldalas dokumentumok készíthetők.

A mesterfájl

Az első változás az úgynevezett "master" dokumentum használata. Ez csak a különálló dokumentum-részekre mutató hivatkozásokat tartalmaz. A formátuma nem tér el túlzottan a GuideXML-ben megszokottól:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<book link="example.xml">
<title>Példa a könyv formátum használatára</title>

<author...>
  ...
</author>

<abstract>
  ...
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>...</version>
<date>...</date>

Eddig nem nagy eltérés, igaz? Csak a <guide> tag helyett a <book> szerepel. Ezután azonban nem az egyes fejezetek <chapter> tagjei jönnek, hanem azok a <part> tagek, amelyek a könyv egyes részeit tartalmazzák:

<part>
<title>Első rész</title>
<abstract>
  ...
</abstract>

(az egyes fejezetek definiálása)
</part>

Minden részt egy <title> és egy <abstract> tag követ, melyek az adott rész rövid bevezetését tartalmazzák.

Az egyes részeken belül definiálod a különálló fejezeteket (<chapter>). Minden fejezet külön dokumentum. Ebből következik, hogy egy speciális tag, az <include> is szükséges, amellyel be tudod szúrni magát szöveget.

<chapter>
<title>Első fejezet</title>
<abstract>
  Ez az első fejezet rövid leírása.
</abstract>

  <include href="elérési/út/chapter-one.xml"/>

</chapter>

Az egyes fejezetek megtervezése

Az önálló fejezetek szerkezete így néz ki:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<!--  The content of this document is licensed under the CC-BY-SA license -->
<!--  See http://creativecommons.org/licenses/by-sa/2.5 -->

<sections>

<version>...</version>
<date>...</date>

(a különböző <section> és <subsection> részek definiálása)

</sections>

A fejezeteken belül szakaszokat (<section>, ugyanaz, mint az Útmutató formátum <chapter>-je) és alszakaszokat (<subsection>, az Útmutató formátum <section>-je) adhatsz meg.

Minden különálló fejezetnek külön dátuma és verziója lehet. A különböző fejezetek és a mester dokumentum közül annak a dátuma kerül böngészés közben kijelzésre, amelyik a legutóbb módosult.

5.  Hogyan tovább?

Csapjunk bele!

Az Útmutató direkt úgy lett megtervezve, hogy amit megtervezel, azt kelljen leírnod is. Így a fejlesztőknek több idejük marad magának a dokumentumnak a megírására, nem kell annyit az XML-kódokkal bíbelődniük. Remélhetőleg ez a doksi- undorban szenvedőknek is segít abban, hogy minőségi Gentoo-leírásokat hozzanak létre. Ehhez érdemes átnézni a Dokumentáció-fejlesztési tippek és trükkök-et. Ha segíteni szeretnél, vagy csak kérdésed van az útmutatóval kapcsolatban, írj egy üzenetet a gentoo-doc levelezési listára, ahol jelezheted szándékodat. Jó szórakozást!

Ez a dokumentum a Creative Commons - Attribution / Share Alike licensz védelme alatt áll.