Sintaxa ghidului XML este simplificată dar expresivă, deci este simplu de învăţat dar pune la dispoziţie toate facilităţile necesare scrierii de documentaţie web. Numărul de tag-uri este redus la minimum -- doar ceea ce este necesar. Acest lucru face uşoară transformarea ghidului în alte formate, cum ar fi DocBook XML/SGML sau HTML, gata de publicare.

Scopul este de a simplifica procedura de creare şi transformare a documentelor ghid XML.

Dacă planificaţi să scrieţi documentaţie Gentoo sau doriţi să testaţi Ghidul XML, vă rugăm să citiţi Sfaturi şi Trucuri pentru Documentaţie ce conţine sfaturi şi diverse trucuri utile creatorilor de documentaţie Gentoo.

Puteţi să aruncaţi o privire şi asupra sursei XML a acestui document, în timp ce-l consultaţi.

Haideţi să pornim învăţarea sintaxei GhidXML. Vom porni cu tag-urile iniţiale (antet) folosite în documentele GhidXML:

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

<guide link="/doc/ro/ghid.xml" lang="ro">
<title>Ghid Documentaţie Gentoo</title>

<author title="Author">
  <mail link="adresata@gentoo.ro">Numele Tău</mail>
</author>

<abstract>
Acest ghid ne arată cum să scriem documentaţie folosind noua sintaxă
simplificată Gentoo GhidXML. Această sintaxă este formatul oficial pentru
documentaţia Gentoo şi chiar acest document a fost creat folosind
GhidXML.
</abstract>

<!-- Conţinutul acestui document este sub licenţă CC-BY-SA  -->
<!-- Detalii la http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

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

În prima linie observăm tag-ul necesar identificării documentului XML şi a schemei DTD. Linia <!-- $Header$ --> va fi automat modificată de sistemul server CVS şi ajută la urmărirea reviziilor. Imediat după, este un tag <guide> -- întregul ghid este cuprins în perechea <guide> </guide>. Atributul link este obligatoriu şi ar trebui să conţină calea absolută la document relativ la calea rădăcină unde se află documentele chiar dacă funcţionează şi specificând doar numele fişierului. Scopul lui principal este de a genera o legătură "versiune printabilă" la documentul dumneavoastră. Dacă veţi folosi o valoare incorectă, legătura "versiune printabilă" nu va funcţiona sau va indica un alt document. Documentele traduse trebuie să specifice calea completă, pentru că este utilizată, de asemenea, pentru a verifica dacă există un document original mai recent. Atributul lang ar trebui folosit pentru a specifica limba în care este scris documentul. Este folosit pentru a formata data precum şi afişarea etichetelor ca "Notă", "Conţinut", etc. în limba specificată. Valoarea implicită este Engleza.

Mai departe este un tag <title> folosit pentru a seta titlul pentru întregul document.

Apoi ajungem la tag-urile <author> ce conţin informaţii despre diverşii autori ai documentului. Fiecare tag <author> permite un element opţional title folosit pentru a specifica tipul de contribuţie al autorului (autor, coautor, editor, translator, etc.). În acest exemplu particular numele autorului este cuprins în altă pereche -- tag-ul <mail>, folosit pentru a specifica adresa de mail pentru acest autor. Tag-ul <mail> este opţional şi este suficient un singur element <author> într-un ghid (pot fi oricâte astfel de elemente).

Mai departe observăm tag-urile <abstract>, <version> şi <date>, folosite pentru a specifica un sumar al documentului, numărul versiunii curente precum şi data acestei versiuni (în format YYYY-MM-DD). Datele invalide sau ce nu sunt în formatul YYYY-MM-DD nu vor fi formatate ci vor fi afişate aşa cum au fost scrise în documentul generat.

Cam atât despre tag-urile ce trebuie să apară la începutul unui document ghid. În afară de <title> şi <mail>, aceste tag-uri nu trebuie să apară decât imediat după tag-ul <guide>, şi pentru consistenţă, se recomandă (dar nu obligatoriu) ca aceste tag-uri să apară înainte de conţinutul documentului.

În final avem tag-ul <license/>, folosit pentru a publica documentul sub licenţă Creative Commons - Attribution / Share Alike şi acest lucru este impus de Politica pentru Documentaţie.

Odată ce tag-urile iniţiale au fost specificate, sunteţi gata să adăugaţi elementele de structură ale documentului. Documentele Ghid sunt împărţite în capitole, fiecare capitol putând conţine una sau mai multe secţiuni. Fiecare capitol şi secţiune au un titlu. Aici aveţi un capitol exemplu cu o singură secţiune compusă dintr-un paragraf. Dacă adăugaţi acest cod XML la codul XML anterior şi adăugaţi tag-ul </guide> la finalul fişierului, veţi obţine un document Ghid valid (chiar dacă minimal):

<chapter>
<title>Acesta este capitolul meu</title>
<section>
<title>Aceasta este secţiunea unu din capitolul meu</title>
<body>

<p>
Acesta este conţinutul din secţiunea unu a capitolului meu.
</p>

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

Deasupra am setat titlul capitolului adăugând un element copil <title> pentru elementul <chapter>. Apoi am creat o secţiune adăugând un element <section>. Dacă priviţi în interiorul elementului <section> veţi observa că acesta conţine două elemente copil -- un element <title> şi unul <body>. În timp ce <title> nu este nou pentru noi, elementul <body> este -- acesta înglobează conţinutul efectiv al secţiunii. Vom analiza pe larg elementele ce sunt permise în interiorul elementului <body>.

Acum este timpul să învăţăm cum să formatăm conţinutul efectiv al documentului. Aici este codul XML pentru un exemplu de element <body>:

<p>
Acesta este un paragraf.  <path>/etc/passwd</path> este un fişier.
<uri>http://www.gentoo.ro</uri> este situl meu favorit.
Tastaţi <c>ls</c> dacă doriţi asta.  Eu <e>chiar</e> vreau să merg la culcare.
</p>

<pre caption="Mostră de cod">
Acesta este ieşirea unui program sau un fragment de cod
# <i>acesta este introdus de utilizator</i>

Creaţi HTML/XML uşor de citit folosind selectiv accentuările:
<foo><i>bar</i></foo>

<comment>(Aşa se introduce o notă într-un bloc de cod)</comment>
</pre>

<note>
Aceasta este o notă.
</note>

<warn>
Aceasta este o atenţionare.
</warn>

<impo>
Acesta este important.
</impo>

Acum, iată cum este generat elementul <body> de mai sus:

Acesta este un paragraf. /etc/passwd este un fişier. http://www.gentoo.ro este site-ul meu favorit. Tastaţi ls dacă doriţi asta. Eu chiar vreau să merg la culcare.

Acesta este ieşirea unui program sau cod.
# acesta este introdus de utilizator

Creaţi HTML/XML uşor de citit folosind selectiv accentuările:
<foo>bar</foo>

(Aşa se introduce o notă într-un bloc de cod)

Am introdus în secţiunea precedentă o mulţime de tag-uri noi -- iată ce trebuie să ştiţi. Tag-urile <p> (paragraf), <pre> (bloc de cod), <note> (notă), <warn> (atenţionare) şi <impo> (important), toate pot conţine una sau mai multe linii de text. Exceptând <table>, <ul>, <ol> şi <dl> (ce vor fi prezentate imediat), doar aceste tag-uri trebuie să apară imediat în interiorul elementului <body>. Un alt lucru -- aceste tag-uri nu trebuie să fie imbricate -- cu alte cuvinte, nu puneţi un element <note> în interiorul unui element <p>. Aşa cum intuiţi, elementul <pre> păstrează spaţiile exact cum sunt scrise, făcându-l propice pentru listare de cod. Trebuie să etichetaţi tag-ul <pre> cu un atribut caption:

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

Delegaţii din cele 13 state originale au format Congresul. Thomas Jefferson, cineva din Virginia şi Benjamin Franklin au fost doi cântăreţi ai Declaraţiei de Independenţă. Frankling a descoperit electricitatea prin frecarea a două pisici pe spate şi a declarat, "Un cal împărţit de către el nu poate rezista.". Franklin a murit în 1790 şi este încă mort.

Epigrafele sunt utilizate uneori la începutul capitolelor pentru a ilustra ceea ce va urma. Este pur şi simplu un paragraf cu un atribut by ce conţine semnătura.

<p by="Student anonim">
Delegaţii din cele 13 state originale au format...
</p>

Elementele <path>, <c>, <e>, <sub> şi <sup> pot fi folosite în interiorul oricărui element copil al tag-ului <body>, exceptând <pre>.

Elementul <path> este folosit pentru a marca textul ce face referire la un fişier de pe disc -- oricum ar fi cale absolută sau relativă, sau un simplu nume de fişier. Acest element este, în general, afişat cu un font monospaţiat pentru a-l diferenţia de un paragraf standard.

Elementul <c> este folosit pentru a marca o comandă sau date introduse de utilizator. Gândiţi-vă la <c> ca la un mod de a atenţiona cititorul că urmează ceva ce trebuie să tasteze pentru a efectua anumite acţiuni. De exemplu toate tag-urile XML afişate în acest document sunt afişate folosind elementul <c> deoarece reprezintă ceva ce utilizatorul ar trebui să scrie şi nu reprezintă o cale. Folosind elemente <c> veţi ajuta cititorii să identifice rapid comenzile pe care vor fi nevoiţi să le tasteze. De asemenea, deoarece elementele <c> sunt gata diferenţiate de textul obişnuit, foarte rar va fi necesar de a încadra textul de introdus între ghilimele. De exemplu, nu folosiţi elementul "<c>", vedeţi ce am scris anterior. Evitaţi să folosiţi ghilimelele ce nu sunt necesare pentru a face documentul mult mai citibil -- şi delicios!

Aşa cum, probabil, aţi ghicit, <b> este utilizat pentru a îngroşa un text.

<e> este folosit pentru a accentua un cuvânt sau o frază; de exemplu: Eu chiar ar trebui să folosesc punct şi virgulă mai des. După cum vedeţi, acest text este diferenţiat faţă de textul obişnuit tocmai pentru a se evidenţia accentuarea cuvântului. Acesta vă ajută să daţi frazelor mai multă culoare!

Elementele <sub> şi <sup> sunt utilizate pentru a specifica un _index sau un ^exponent.

Pentru a îmbunătăţi lizibilitatea mostrelor de cod, sunt permise următoarele tag-uri în interiorul blocurilor <pre>:

<i>

Distinge ceea ce introduce utilizatorul de textul afişat

<comment>

Comentarii relevante acţiunii(lor) ce apar după comentariu

<keyword>

Denotă un cuvânt cheie în limbajul utilizat în mostra de cod

<ident>

Utilizat pentru un identificator

<const>

Utilizat pentru o constantă

<stmt>

Utilizată pentru o instrucţiune

<var>

Utilizat pentru o variabilă

Exemplu de bloc de cod <pre> colorat:

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

Mai devreme am aruncat o privire asupra tag-ului <mail>; acesta este folosit pentru a lega un anumit text cu o adresă de mail şi ia forma <mail link="foo@bar.com">Dl. Foo Bar</mail>. Dacă doriţi să afişaţi adresa de e-mail, puteţi utiliza <mail>foo@bar.com</mail>, aceasta fiind afişată ca foo@bar.com.

Tag-ul <uri> este folosit pentru a indica fişiere/locaţii din Internet. Acesta are două forme -- prima poate fi folosită când doriţi ca adresa să fie afişată, cum ar fi această legătură http://www.gentoo.ro. Pentru a crea această legătură am scris <uri>http://www.gentoo.ro</uri>. Forma alternativă este când dorim să asociem o adresă cu alt text -- de exemplu, Comunitatea Gentoo Linux România. Pentru a crea această legătură am scris <uri link="http://www.gentoo.ro">Comunitatea Gentoo Linux România</uri>. Nu este nevoie să scrieţi http://www.gentoo.org/ pentru a indica alte pagini din situl Gentoo. De exemplu o legătură către Index documentaţie ar trebui scrisă simplu <uri link="/doc/ro/index.xml">Index documentaţie</uri>. Eventual puteţi omite index.xml când faceţi referire la un fişier index, adică <uri link="/doc/ro/">Index documentaţie</uri>.

Iată cum putem insera o figură (schiţă, imagine) într-un document -- <figure link="mygfx.png" short="poza mea" caption="poza mea favorită din toate timpurile"/>. Atributul link indică spre imagine, atributul short specifică o scurtă descriere (curent folosită pentru atributul HTML alt= ), şi o etichetă. Nu prea dificil :) De asemenea este suportat în stilul HTML tag-ul <img src="foo.gif"/> pentru a adăuga imagini fără etichete, margini, etc.

Ghidul suportă o sintaxă simplificată pentru tabele, similară sintaxei HTML. Pentru a începe un tabel, folosiţi tag-ul <table>. Începem un rând cu tag-ul <tr>. Totuşi, pentru a adăuga conţinutul efectiv, nu este suportat tag-ul HTML <td>; în loc de acesta se va folosi <th> dacă inseraţi un antet, respectiv <ti> când inseraţi conţinut normal. Puteţi folosi <th> oriunde se poate folosi <ti> -- nu este obligatoriu ca elementele <th> să apară numai ca prim rând.

În plus, tag-ul pentru capul de tabel (<th>) şi elementele de tabel (<ti>) acceptă atributele colspan şi rowspan pentru a plasa titlurile de-a lungul mai multor rânduri, coloane sau ambele, aşa cum este exemplificat mai jos:

Mai mult, elementele de tabel (<ti>) pot fi aliniate la dreapta sau centrate cu ajutorul atributului align. Capetele de tabel (<th>) sunt centrate automat.

Pentru a crea liste ordonate sau neordonate folosiţi în stilul XHTML tag-urile <ol>, <ul> şi <li>. Tag-urile listă trebuie să apară numai în interiorul tag-urilor <body> şi <li> sau <dd> ceea ce înseamnă că putem avea liste în interiorul altor liste. Nu uitaţi că scrieţi în limbajul XML şi că trebuie să închideţi toate tag-urile, spre deosebire de HTML.

Listele de definiţie (<dl>) sunt, de asmenea, suportate. Vă rugăm să notaţi că nici tag-ul termenului de definiţie (<dt>) şi nici cel de date (<dd>) nu acceptă un alt nivel de bloc, ca paragrafele şi avertizările. O listă de definiţii include:

<dl>

Un tag Definiţie de Listă ce conţine

<dt>

Perechi de tag-uri pentru Definiţii de Termeni

<dd>

şi tag-uri pentru Definirea de Date

Următoarea listă copiată de la w3.org arată că o listă de definiţii poate conţine liste ordonate şi neordonate. Nu poate conţine o altă listă, totuşi.

Ingredientele:

• 100 g. făină
• 10 g. zahăr
• 1 cană cu apă
• 2 ouă
• sare, piper

Procedura:

1. Amestecaţi bine ingredientele uscate
2. Turnaţi ingredientele lichide
3. Amestecaţi pentru 10 minute
4. Coaceţi pentru o oră la 300 de grade

Note:

Reţeta poate fi îmbunătăţită prin adăugarea de stafide

Ghidul simplifică foarte mult referirea anumitor părţi din document folosind hiperlegături. Puteţi crea o legătură la Capitolul Unu scriind <uri link="#doc_chap1">Capitolul Unu</uri>. Pentru a indica secţiunea doi din Capitolul Unu, scrieţi <uri link="#doc_chap1_sect2">secţiunea doi din Capitolul Unu</uri>. Pentru a referi figura 3 din capitolul 1, scrieţi <uri link="#doc_chap1_fig3">figura 1.3</uri>. Sau, pentru a referi blocul de cod 2 din capitolul 2, scrieţi <uri link="#doc_chap2_pre2">blocul de cod 2.2</uri>.

Totuşi, anumite documente ghid se schimbă destul de des şi folosirea acestui stil "numărare" poate conduce la legături incorecte. Pentru a preveni acest lucru, puteţi defini diverse nume pentru <chapter>, <section> sau <tr> folosind atributul id şi legându-vă la acest atribut ca aici:

<chapter id="ceva">
<title>Acesta este ceva!</title>
...
<p>
Mai multe informaţii pot fi găsite în <uri link="#ceva">capitolul ceva</uri>
</p>

Un atribut disclaimer (avertisment) poate fi aplicat documentelor ghid şi manual pentru a afişa un avertisment predefinit în partea superioară a documentului. Avertismentele disponibile sunt:

• articles este utilizat pentru articolele republicate
• draft este utilizat pentru a indica faptul că un document este încă în lucru şi nu ar trebui considerat oficial
• oldbook este utilizat pentru manualele vechi pentru a indica faptul că nu mai sunt întreţinute
• obsolete este utilizat pentru a marca un document ca fiind învechit.

Când marcaţi un document ca învechit, ar trebui să adăugaţi un link către o nouă versiune. Atributul redirect există exact pentru acest lucru. Utilizatorul ar putea fi redirectat automat către pagina nouă, însă nu ar trebui să vă bazaţi pe acest comportament.

<?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>Ghidul de Instalare Gentoo pentru arhitectura x86</title>

<author title="Autor">
...

Cât timp toată Documentaţia Gentoo este un efort colectiv şi mulţi dezvoltatori probabil vor dori să modifice documentaţia existentă, un stil de redactare este necesar. Stilul de redactare conţine două secţiuni. Prima secţiune se referă la stilul intern - cum plasăm tag-urile XML. A doua secţiune se referă la conţinut - cum să evităm confuziile în rândul cititorilor.

Ambele secţiuni sunt descrise mai jos.

Trecerea la linie nouă trebuie efectuată imediat după fiecare tag GhidXML (atât tag-ul de deschidere cât şi cel de închidere), exceptând: <version>, <date>, <title>, <th>, <ti>, <li>, <i>, <e>, <uri>, <path>, <b>, <c>, <comment>, <mail>.

Linii goale trebuie adăugate imediat după fiecare <body> (numai tag-ul de deschidere) şi înainte de fiecare <chapter>, <p>, <table>, <author> (set), <pre>, <ul>, <ol>, <warn>, <note> şi <impo> (numai tag-urile de deschidere).

Ruperea rândurilor trebuie aplicată la 80 de caractere exceptând interiorul <pre>. Vă puteţi abate de la această regulă atunci când nu există nici o altă opţiune (de exemplu când un URL depăşeşte maximul de caractere permis). Editorul trebuie să rupă rândul când apare primul caracter spaţiu. Ar trebui să încercaţi să păstraţi conţinutul afişat al elementelor <pre> în limita a 80 de coloane pentru a ajuta utilizatorii de consolă.

Indentarea poate să nu fie folosită, exceptând construcţiile XML ale căror tag-uri părinte sunt <tr> (din <table>), <ul>, <ol>, <dl> şi <author>. Dacă se foloseşte indentarea, atunci aceasta trebuie să fie de două spaţii pentru fiecare indentare. Aceasta înseamnă fără caractere tab şi fără mai multe spaţii. În plus, caracterele tab nu sunt permise în documentele GuideXML.

În cazul în care ruperea rândurilor apare în construcţiile <ti>, <th>, <li> sau <lt>, indentarea trebuie folosită pentru conţinut.

Un exemplu de indentare este:

<table>
<tr>
  <th>Ceva</th>
  <th>Altceva</th>
</tr>
<tr>
  <ti>Acesta este un exemplu de indentare</ti>
  <ti>
    În cazul în care textul nu încape pe o linie de 80 de caractere,
    trebuie să folosiţi indentarea dacă tag-ul părinte vă permite
  </ti>
</tr>
</table>

<ul>
  <li>Prima opţiune</li>
  <li>A doua opţiune</li>
</ul>

Atributele nu trebuie să conţină spaţii între atribut, semnul "=" şi valoarea atributului. De exemplu:

Greşit:     <pre caption = "Atribut">
Corect:     <pre caption="Atribut">

În interiorul tabelelor (<table>) şi listelor (<ul> şi <ol>) şi <dl>, punctul (".") nu trebuie folosit cât timp nu scrieţi mai multe propoziţii. În acest caz, fiecare propoziţie trebuie să se termine cu un punct (sau alt semn final de punctuaţie).

Fiecare propoziţie, inclusiv cele din interiorul tabelelor şi listelor trebuie să înceapă cu o majusculă.

<ul>
  <li>Fără punct</li>
  <li>Cu punct. Multiple propoziţii, vă reamintiţi?</li>
</ul>

Listările (blocurile) de Cod trebuie întotdeauna să aibă etichetă.

Încercaţi să folosiţi <uri> cu atributul link cât de mult este posibil. Cu alte cuvinte, scrierea Gentoo România este preferabilă scrierii http://www.gentoo.ro.

Când faceţi un comentariu în interiorul construcţiei <pre>, folosiţi <comment> şi paranteze sau marcajul de comentariu din limbajul folosit (# pentru scripturi bash şi multe altele, // pentru cod C, etc.) De asemenea plasaţi comentariu înainte de subiectul comentat.

(Înlocuiţi "john" cu numele dumneavoastră de utilizator)
# id john

Pentru documentaţia voluminoasă, cum ar fi Instrucţiunile de Instalare, este nevoie de un format extins. Am proiectat nişte îmbunătăţiri compatibile cu GhidXML care ne permit scrierea de documentaţie modulară şi pe mai multe pagini.

Prima schimbare este nevoia de a avea un document "principal". Acest document nu conţine conţinut real, însă leagă diferitele părţi (module) ale documentaţiei. Sintaxa nu diferă cu mult faţă de GhidXML:

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

<book link="exemplu.xml">
<title>Exemplu folosire carte</title>

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

<abstract>
  ...
</abstract>

<!-- Conţinutul acestui document este sub licenţă CC-BY-SA  -->
<!-- Detalii la http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

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

Deci, în mare, nu sunt diferenţe (exceptând atributul <book> în locul atributului <guide>). În loc de a începe cu tag-uri <chapter> veţi defini <part> ce sunt echivalente cu părţile separate ale cărţii:

<part>
<title>Partea Întâi</title>
<abstract>
  ...
</abstract>

(Definirea diferitelor capitole)
</part>

Fiecare parte este însoţită de un atribut <title> şi un atribut <abstract> ce ne furnizează câteva informaţii introductive despre conţinut.

În interiorul fiecărei părţi veţi defini capitolele (<chapter>). Fiecare capitol trebuie să fie un document separat. Deci nu ar trebui să ne surprindă că un tag special (<include>) este adăugat pentru a permite includerea documentelor separate.

<chapter>
<title>Capitolul Unu</title>
<abstract>
  O succintă explicaţie a capitolului unu.
</abstract>

  <include href="cale/la/capitol-unu.xml"/>

</chapter>

Conţinutul unui capitol individual este structurat după cum urmează:

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

<!--  Conţinutul acestui document este sub licenţă CC-BY-SA -->
<!--  Detalii la http://creativecommons.org/licenses/by-sa/2.5 -->

<sections>

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

(Definiţi diferitele secţiuni, <section> şi <subsection>)

</sections>

În interiorul fiecărui capitol puteţi defini secţiuni (<section>) (echivalentul capitolelor (<chapter>) în Ghid) şi subsecţiuni (<subsection>) (echivalentul secţiunilor (<section>) în Ghid).

Fiecare capitol individual trebuie să conţină propriile elemente dată şi versiune. Ultima dată din toate capitolele va fi afişată când utilizatorul răsfoieşte toate părţile din carte.

Ghidul a fost special proiectat să fie "sărăcăcios şi mediocru" pentru ca dezvoltatorii să petreacă mai mult timp cu scrierea documentaţiei şi mai puţin cu învăţarea actualei sintaxe XML. Sperăm că acest lucru va permite dezvoltatorilor care nu sunt de obicei pricepuţi în formatarea de documentaţie să înceapă scrierea de documentaţie Gentoo de calitate. Probabil veţi fi interesaţi şi de Sfaturi şi trucuri pentru Scrierea de Documentaţie. Dacă doriţi să ne ajutaţi (sau aveţi unele întrebări referitoare la Ghid), vă rugăm să scrieţi pe lista de discuţii gentoo-doc. Distracţie plăcută!