Guida a Gentoo GuideXML

1.  I fondamenti di GuideXML

GuideXML: obiettivi

La sintassi GuideXML è leggera ma espressiva, essendo in questo modo facile da imparare, ed offrendo allo stesso tempo tutto ciò di cui si ha bisogno per creare documentazione per il web. Il numero dei tag è mantenuto al minimo indispensabile. Questo rende facile trasformare i documenti in altri formati come DocBook XML/SGML o vere e proprie pagine HTML.

L'obiettivo è di creare e convertire facilmente documenti GuideXML.

Ulteriori risorse

Se si desidera contribuire alla documentazione di Gentoo, o se si vuole provare Guide XML, leggere la guida Trucchi e consigli per lo sviluppo della documentazione, che contiene consigli e trucchi per lo sviluppo di documentazione.

È possibile guardare il sorgente XML di questo stesso documento mentre lo si sta leggendo.

2.  GuideXML

Struttura di base

La prima cosa da fare è imparare la sintassi Guide XML. Si comincerà con il tag d'inizio usato in un documento Guide XML:

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

<guide link="/doc/it/guide.xml" lang="it">
<title>Guida alla Documentazione Gentoo</title>

<author title="Autore">
  <mail link="tuonome@gentoo.org">Tuo Nome</mail>
</author>

<abstract>
Questa guida mostra come produrre documentazione web utilizzando la nuova e
leggera sintassi Gentoo Guide XML. Questa sintassi è il formato ufficiale della
documentazione Gentoo, e questo stesso documento è stato creato utilizzando
Guide XML. Questa guida presuppone una conoscenza base di XML e HTML.
</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>2001-03-29</date>

Nelle prime linee, c'è il tag che identifica il documento come un documento XML e ne specifica il DTD. La riga <!-- $Header$ --> sarà modificata dal server CVS e serve per tenere traccia del numero delle revisioni. Segue il tag <guide>: l'intero documento è racchiuso all'interno di una coppia di tag <guide> </guide>.
L'attributo link è opzionale e dovrebbe contenere il percorso assoluto al documento relativamente alla root della documentazione, anche se il nome del file senza percorso funzionerà ugualmente. E' usato solamente per generare un collegamento ad una versione facilmente stampabile del documento e per controllare se una traduzione è aggiornata. Il nostro motore XSL passa il percorso reale della guida al foglio di stile XSL. L'attributo link è utilizzato solamente come un valore di riserva, nel caso che l'XML venga processato in un altro modo.
L'attributo lang dovrebbe essere utilizzato per specificare il codice del linguaggio del documento. Esso è utilizzato per formattare la data e per inserire le stringhe come "Nota", "Indice", ecc. nel linguaggio corretto. Il linguaggio predefinito è l'inglese.

Segue un tag <title>, usato per definire il titolo dell'intero documento.

Si arriva ai tag <author>, che contengono informazioni relative ai vari autori del documento. Ogni tag <author> accetta un elemento opzionale title, utilizzato per specificare la relazione tra l'autore e il documento (author, co-author, editor, etc.). In questo esempio, il nominativo dell'autore è racchiuso in un altro tag <mail>, usato per specificare un indirizzo email relativo all'autore. Il tag <mail> è opzionale e può essere omesso mentre è necessario almeno un tag <author> per documento.

Successivamento si trovano i tag <abstract>, <version> e <date>, usati per specificare rispettivamente un riassunto del documento, il numero di versione corrente, e la data della versione corrente (nel formato YYYY-MM-DD). Date non valide o non nel formato YYYY-MM-DD appariranno non formattate (verbatim) nel documento.

Questo riassume i tag che dovrebbero apparire all'inizio di un documento di guida. Insieme ai tag <title> e <mail>, questi tag dovrebbero apparire immediatamente dentro il tag <guide> e in nessun'altra parte del documento, e per coerenza con il resto della documentazione, è raccomandato (ma non richiesto) che questi tag appaiano prima del contenuto del documento.

Infine c'è il tag <license/>, usato per pubblicare il documento sotto la licenza Creative Commons - Attribution / Share Alike, come richiesto dalla Politica della Documentazione di Gentoo Linux.

Capitoli e sezioni

Una volta specificati i tag iniziali, si è pronti per iniziare ad aggiungere elementi strutturali al documento. I documenti sono divisi in capitoli, e ogni capitolo può avere una o più sezioni. Capitoli e sezioni hanno sempre un titolo. Segue un capitolo d'esempio con una singola sezione, composta da un paragrafo. Se si accoda questo codice XML all'esempio precedente e si termina il tutto con </guide>, si otterrà un documento valido (anche se minimale):

<chapter>
<title>Questo è il mio capitolo</title>
<section>
<title>Questa è la sezione del mio capitolo</title>
<body>

<p>
Questo è il paragrafo della mia sezione.
</p>

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

Sopra, è stato inserito il titolo del capitolo, aggiungendo un elemento <title> figlio dell'elemento <chapter>. Quindi, è stato creato una sezione, aggiungendo un elemento <section>. Guardando all'interno dell'elemento <section> si vedranno due elementi figli: <title> e <body>. Mentre <title> non è nuovo, lo è <body>, che contiene l'attuale testo all'interno di una data sezione. Si vedranno ora quali tag sono permessi all'interno dell'elemento <body>.

Un esempio di <body>

E' tempo di imparare ad arricchire il contenuto della guida. Ecco un esempio di codice XML per l'elemento <body>:

<p>
Questo è un paragrafo. <path>/etc/passwd</path> è un file.
<uri>http://forums.gentoo.org</uri> è il mio sito preferito.
Se hai voglia digita <c>ls</c>. Voglio <e>davvero</e> andare a dormire.
</p>

<pre caption="Code Sample">
Questo è l'output.
# <i>questo è l'input dell'utente</i>

Rendi l'HTML/XML facile da leggere evidenziando in maniera selettiva:
<foo><i>bar</i></foo>

<comment>(Ecco come inserire un commento in un blocco di codice)</comment>
</pre>

<note>
Questa è una nota.
</note>

<warn>
Questo è un warning.
</warn>

<impo>
Questo è importante.
</impo>

Ecco ora, come appare l'elemento <body> dell'esempio qui sopra:

Questo è un paragrafo. /etc/passwd è un file. http://forums.gentoo.org è il mio sito preferito. Se hai voglia digita ls. Voglio davvero andare a dormire.

Questo è l'output.
# questo è l'input dell'utente

Rendi l' HTML/XML facile da leggere evidenziando in maniera selettiva:
<foo>bar</foo>

(Ecco come inserire un commento in un blocco di codice)

I tag <body>

Sono stati introdotti molti nuovi tag nella sezione precedente, ecco quello che è necessario sapere. I tag <p> (paragrafo), <pre> (blocco di codice), <note>, <warn> (warning) e <impo> (importante), possono tutti contenere una o più linee di testo. Oltre l'elemento <table>, <ul>, <ol> e <dl> (che verranno analizzati tra poco), ci sono tag che dovrebbero apparire immediatamente all'interno dell'elemento <body>. Inoltre, questi tag non dovrebbero essere innestati: in altre parole, non mettere un elemento <note> all'interno di un elemento <p>. Come si potrà facilmente indovinare, l'elemento <pre> preserva esattamente i suoi spazi, diventando un ottimo elemento per blocchi di codice. In questo casi bisogna specificare un attributo caption per il tag <pre>:

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

Epigrafi

I delegati dei 13 stati originali hanno formato il Congresso. Thomas Jefferson e Benjamin Franklin sono stati due artefici della Dichiarazione di Indipendenza. Franklin ha scoperto l'elettricità accarezzando due gatti e ha dichiarato "Un cavallo diviso non può stare in piedi". Franklin è morto nel 1790 ed è ancora morto.

—Studente anonimo

Le epigrafi a volte sono usate all'inizio dei capitoli per introdurre quello che segue. E' un semplice paragrafo con un attributo by che contiene la frase.

<p by="Studente anonimo">
I delegati dei 13 stati originali hanno formato...
</p>

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

Gli elementi <path>, <c>, <b>, <e>, <sub> e <sup> possono essere usati all'interno di ogni tag figlio del tag <body>, ad eccezione di <pre>.

L'elemento <path> è usato per marcare testo che si riferisce ad un file su disco, sia esso un percorso assoluto o relativo, o semplicemente un nome di file. Questo elemento è generalmente rappresentato con un font monospaced per differenziarlo dal tipo standard utilizzato nel paragrafo.

L'elemento <c> è usato per marcare un comando o l'input dell'utente. Pensare a <c> come ad un modo di avvertire il lettore di qualcosa che se digitato esegue qualche tipo di azione. Per esempio, tutti i tag XML visibili in questo documento sono racchiusi tra elementi <c> perché rappresentano qualcosa che l'utente potrebbe digitare. Usando elementi <c>, si aiuteranno i propri lettori ad identificare facilmente i comandi che hanno bisogno di essere digitati. Poiché gli elementi <c> sono distinti dal testo regolare, è raramente necessario delimitare l'input utente tra doppi apici. Per esempio, non fare riferimento ad un elemento "<c>" come viene fatto in questa frase. Evitando l'uso di doppi apici non necessari, si rende il documento più leggibile.. e carino!

Come si potrà immaginare, <b> è usato per scrivere in grassetto una parte di testo.

<e> è usato per per dare enfasi ad una parola o ad una frase. Ad esempio: dovrei utilizzare punti e virgola veramente più spesso. Come si può vedere, questo testo è distinto dal resto del paragrafo per dare enfasi. Questo aiuta a rafforzare le proprie idee!

<sub> e <sup> sono usati per specificare _subscript e ^superscript.

Esempi di codice e codice colorato

Per migliorare la leggibilità degli esempi di codice, i tag seguenti sono consentiti all'interno di blocchi <pre>:

<i>

Distingue l'input dell'utente dal testo visualizzato

<comment>

Commenti relativi alle azioni che seguono il commento

<keyword>

Denota una parola chiave nel linguaggio utilizzato all'interno dell'esempio di codice

<ident>

Utilizzato per un identificatore

<const>

Utilizzato per una costante

<stmt>

Utilizzato per uno statement

<var>

Utilizzato per una variabile

Esempio di blocco <pre> con codice colorato:

# Copyright 1999-20069 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
   emake || die "emake failed"
}

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

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

<mail> e <uri>

Precedentemente si è visto il tag <mail>; è usato per collegare del testo con un particolare indirizzo email, con la seguente sintassi <mail link="foo.bar@example.com">Mr. Foo Bar</mail>. Se si vuole visualizzare l'indirizzo email, è possibile usare <mail>foo.bar@example.com</mail>, e sarà visualizzato come foo.bar@example.com.

Alcune forme abbreviate facilitano l'utilizzo di nomi ed email degli sviluppatori di Gentoo. Sia <mail>neysx</mail> che <mail link="neysx"/> appariranno come Xavier Neys. Se si vuole utilizzare l'email di uno sviluppatore di Gentoo con un contenuto diverso dal suo nome completo, utilizzare la seconda forma specificando il contenuto da mostrare. Ad esempio, per mostrate solo il nome dello sviluppatore: <mail link="neysx">Xavier</mail> appare come Xavier.
Ciò è particolarmente utile quando si vuole scrivere il nome di uno sviluppatore il cui nome contiene caratteri "particolari" che non si è in grado di scrivere.

Il tag <uri> è usato per puntare a file o indirizzi Internet. Assume due forme: la prima può essere usata quando si vuole mostrare un URI nel corpo del testo, come questo link a http://forums.gentoo.org/. Per creare questo link, è stato digitato <uri>http://forums.gentoo.org/</uri>. Utilizzare la forma alternativa quando si vuole associare un URI con qualche altro testo, per esempio, Forum Gentoo. Per creare questo link, è stato digitato <uri link="http://forums.gentoo.org/">Forum Gentoo</uri>. Non è necessario scrivere http://www.gentoo.org/ per collegare altre parti del sito web di Gentoo. Per esempio, un collegamento a Documentazione Gentoo dovrebbe essere semplicemente definito con <uri link="/doc/it/index.xml">Documentazione Gentoo</uri>. È possibile omettere anche index.xml quando si crea un collegamento a una directory indice, per esempio, <uri link="/doc/it/">Documentazione Gentoo</uri>. Scrivere la slash finale risparmia una richiesta HTTP aggiuntiva.

Non si dovrebbe utilizzare un tag <uri> un un attributo link che incomincia con mailto:. In questo caso utilizzare un tag <mail>.

Si prega di evitare la sindrome da clicca qui come raccomandato dal W3C.

Figure

Ecco come inserire una figura in un documento: <figure link="mygfx.png" short="la mia figura" caption="la mia figura preferita "/>. L'attributo link punta all'attuale immagine grafica, l'attributo short specifica una descrizione (usata correntemente per l'attributo alt per le immagini HTML), e caption specifica una didascalia. Nulla di troppo difficile :) E' supportato anche il tag HTML <img src="foo.gif"/> per aggiungere immagini senza didascalia, bordi, ecc.

Tabelle

Così come in HTML, il sistema GuideXML supporta una sintassi semplificata per le tabelle. Per iniziare un tabella, usare un tag <table>. Cominciare una riga con il tag <tr>. Tuttavia, per inserire i dati nella tabella, non è supportato il tag HTML <td>; si utilizza, invece, <th> per inserire una intestazione, e <ti> per blocchi di informazioni. Si può usare <th> ovunque sia possibile utilizzare il tag <ti>, non è richiesto che l'elemento <th> sia presente solo nella prima riga.

Inoltre, sia le intestazioni delle tabelle (<th>) che gli elementi (<ti>) delle tabelle accettano gli attributi colspan e rowspan per estendere il loro contenuto su più righe, colonne o entrambe.

Inoltre, le celle della tabella (<ti> & <th>) possono avere un allineamento sulla destra, sulla sinista o al centro tramite l'attributo align.

Liste

Per creare liste ordinate e non, usare semplicemente i tag stile XHTML <ol>, <ul> e <li>. I tag lista dovrebbero apparire solo all'interno dei tag <body> e <li>, il che significa che è possibile avere liste dentro liste. Non bisogna scordarsi che si sta scrivendo XML e che è necessario chiudere tutti i tag, inclusi gli elementi delle liste, diversamente da HTML.

Sono supportate le definizioni di liste (<dl>). Nè il tag di definizione del termine, (<dt>) nè il tag di definizione dei dati (<dd>) accettano altri tag di paragrafi o note. Una definizione di lista comprende

<dl>

Un tag di Definizione Lista contentente

<dt>

coppie di tag Definizione-Termine

<dd>

e Definizione-Dati

La seguente lista copiata da w3.org mostra come una definizione di lista possa contenere liste ordinate e non. Non può invece contenere un'altra definizione di lista.

Ingredienti:

• 100 g. di farina
• 10 g. di zucchero
• 1 tazzina di acqua
• 2 uova
• sale, pepe

Procedura:

1. Mischiare gli ingredienti
2. Versare gli ingredienti bagnati
3. Mischiare per 10 minuti
4. Cuocere per 1 ora a 300 gradi

Note:

La ricetta può essere migliorata aggiungendo uva passa

Riferimenti interni al documento

GuideXML rende veramente semplice fare riferimento ad altre parti di un documento usando collegamenti ipertestuali (hyperlinks). È possibile creare un collegamento che punti a Capitolo 1 digitando <uri link="#doc_chap1">Capitolo 1</uri>. Per puntare alla Sezione 2 del Capitolo 1, digitare <uri link="#doc_chap1_sect2">Sezione 2 del Capitolo 1</uri>. Per riferirsi alla Figura 3 nel Capitolo 1, digitare <uri link="#doc_chap1_fig3">Figura 1.3</uri>. O, per riferirsi al Listato 2 nel Capitolo 2, digitare <uri link="#doc_chap2_pre2">Listato 2 nel Capitolo 2</uri>.

Tuttavia, alcune guide cambiano spesso, e vi possono essere alcuni link non più esatti. Per evitare questo, si può definire un nome per un <chapter>, <section> o <tr> usando l'attributo id, e poi puntare a esso, così:

<chapter id="foo">
<title>Questo è foo!</title>
...
<p>
Ulteriori informazioni possono essere trovate nel
<uri link="#foo">foo chapter</uri>
</p>

Disclaimer e documenti obsoleti

Può essere applicato un attributo disclaimer alle guide e ai manuali per visualizzare un disclaimer predefinito all'inizio del documento. I disclaimer disponibili sono:

• articles è usato per gli articoli ripubblicati
• draft è usato per indicare un documento che è ancora in lavorazione e che non dovrebbe essere considerato ufficiale
• oldbook è usato su vecchi manuali per indicare che non sono più mantenuti
• obsolete è usato per indicare che un documento è obsoleto

Quando si afferma che un documento è obsoleto, si può aggiungere un collegamento alla nuova versione. Ciò che serve in questo caso è l'attributo redirect col quale l'utente è reindirizzato alla nuova pagina.

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

<guide disclaimer="obsolete" redirect="/doc/it/handbook/handbook-x86.xml">
<title>Guida all'installazione di Gentoo su x86</title>

<author title="Autore">
...

Domande frequenti (FAQ)

I documenti delle Domande Frequenti (FAQ) devono iniziare con una lista di domande con i collegamenti alle rispettive risposte. Creare una tale lista richiede molto tempo ed è soggetto ad errori. La lista può essere creata in automatico utilizzando un elemento faqindex come primo capitolo del documento. Questo elemento ha la stessa struttura di chapter per consentire l'inserimento di un testo introduttivo. La struttura del documento è suddivisa in capitoli (almeno un capitolo) contenenti sezioni; ogni sezione contiene una domanda specificata nel suo elemento title con la risposta contenuta nell'elemento body. L'indice delle FAQ apparirà come una sezione per capitolo e un collegamento per ogni domanda.

Uno sguardo veloce alle FAQ e ai suoi sorgenti dovrebbe chiarire ciò che è appena stato spiegato.

3.  Formato dell'Handbook

Guide vs Manuale

Per documentazione molto voluminosa, come Installazione di Gentoo, era necessario un formato più ampio. Abbiamo sviluppato un'estensione GuideXML-compatibile che consente di scrivere documentazione modulare ed estesa su pagine multiple

File Principale

Il primo cambiamento consiste nell'esigenza di creare un documento "master". Questo documento non ha del contenuto effettivo, ma dei collegamenti ai moduli individuali della documentazione. La sintassi non differisce molto da GuideXML:

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

<book>
<title>Esempio di utilizzo di un Manuale</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>

Al momento, nessuna vera differenza (tranne il tag <book> invece di <guide>). Invece di incominciare con i singoli <chapter> , definire un tag <part>, che è l'equivalente di una parte separata in un libro:

<part>
<title>Parte Uno</title>
<abstract>
  ...
</abstract>

(definire i capitoli)
</part>

Ogni parte è accompagnata da un tag <title> e da un tag <abstract> che forniscono una breve introduzione alla parte.

All'interno di ogni parte, definire i singoli<chapter>. Ogni capitolo deve risiedere in un documento separato. Di conseguenza, non deve destare stupore l'aggiunta di un tag speciale (<include>) per consentire di includere i documenti esterni con i capitoli.

<chapter>
<title>Capitolo Uno</title>

<include href="path/to/chapter-one.xml"/>

</chapter>

Definire i Singoli Capitoli

Il contenuto di un singolo capitolo è strutturato nel modo seguente:

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

<abstract>
  Questa è una breve spiegazione del capitolo uno.
</abstract>

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

(Definire le <section> e le <subsection>)

</sections>

All'interno di ogni capitolo è possibile definire <section> (l'equivalente di <chapter> in una guida) e <subsection> (l'equivalente di <section> in una guida).

Ogni singolo capitolo dovrebbe avere i propri elementi <date> e <version>. La data più recente di tutti i capitolo e del documento master verrà mostrata quando un utente navigherà attraverso le parti del manuale.

4.  Caratteristiche Avanzate dell'Handbook

Variabili Globali

Alcune volte, gli stessi valori sono ripetuti molte volte in varie parti dell'handbook. Operazioni di ricerca e sostituzione globali tendono a far sfuggire alcuni valori o a produrre modifiche non volute. Inoltre, potrebbe essere utile definire alcune variabili in capitoli condivisi da vari handbook, in modo che esse assumano valori differenti a seconda di quale handbook include i capitoli.

Variabili globali possono essere definite nel file master dell'handbook ed essere poi utilizzate in tutti i capitoli inclusi.

Per definire delle variabili globali, aggiungere un elemento <values> al file master dell'handbook. Ogni variabile è definita in un elemento <key> il cui attributo id definisce il nome della variabile. Il contenuto di <key> è il valore della variabile.

L'esempio seguente definisce tre valori in un file master di un handbook.

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

<book>
<title>Esempio di utilizzo di un Manuale</title>

<values>
 <key id="arch">x86</key>
 <key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key>
 <key id="min-cd-size">57</key>
</values>

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

  ...

I valori definiti possono poi essere utilizzati attraverso l'intero handbook con l'elemento <keyval id="key_id"/> inserito nel testo. Specificare il nome della variabile nell'attributo id; ad esempio <keyval id="min-cd-name"/> verrebbe sostituito da "install-x86-minimal-2007.0-r1.iso" nel nostro esempio.

<p>
Il CD di Installazione Minimale è chiamato <c><keyval id="min-cd-name"/></c>
e richiede solo <keyval id="min-cd-size"/> MB di spazio su disco.
E' possibile utilizzare questo CD di installazione per installare Gentoo, ma
<e>solo</e> con una connessione Internet attiva.
</p>

Per rendere la vita facile ai traduttori, utilizzare solamente valori che non necessitano di essere tradotti. Ad esempio, abbiamo definito il valore della variabile min-cd-size come 57 e non 57 MB.

Elementi Condizionali

I capitoli che sono condivisi da vari handbook come il Manuale Gentoo contengono spesso delle piccole differenze a seconda di quale handbook li include. Invece di aggiungere contenuto non rilevante ad alcuni handbook, gli autori possono aggiungere una condizione agli elementi seguenti: <section>, <subsection>, <body>, <note>, <impo>, <warn>, <pre>, <p>, <table>, <tr>, <ul>, <ol> and <li>.

La condizione deve essere un'espressione XPATH che verrà valutata quando verrà trasformato l'XML. Se l'espressione avrà valore vero, l'elemento sarà processato, altrimenti verrà ignorato. La condizione è specificata in un attributo test.

L'esempio seguente utilizza il valore arch che è definito in ogni file master dell'handbook per condizionare parte del contenuto:

<body test="contains('AMD64 x86',func:keyval('arch'))">

<p>
Questo paragrafo si applica si all'architettura x86 che AMD64.
</p>

<p test="func:keyval('arch')='x86'">
Questo paragrafo si applica solamente all'architettura x86.
</p>

<p test="func:keyval('arch')='AMD64'">
Questo paragrafo si applica solamente all'architettura AMD64.
</p>

<p test="func:keyval('arch')='PPC'">
Questo paragrafo non sarà mai mostrato!
L'intero corpo sarà saltato a causa della condizione.
</p>

</body>

<body test="contains('AMD64 PPC64',func:keyval('arch'))">

<p>
Questo paragrafo si applica alle architetture AMD64, PPC64 e 
PPC poiché la stringa 'AMD64 PPC64' contiene 'PPC'.
</p>

<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'">
Questa nota si applica solamente alle architetture AMD64 e PPC64.
</note>

</body>

5.  Stile di codifica

Introduzione

E' necessario uno stile di codifica, poiché tutta la documentazione di Gentoo è un lavoro fatto in comune tra molte persone, le quali andranno a modificare la documentazione esistente. Uno stile di codifica è costituito da due parti. La prima riguarda la codifica interna, ossia come vanno messi i tag xml. La seconda riguarda il contenuto, ossia come non confondere il lettore.

Verranno descritte le due parti.

Stile di codifica interno

Si deve andare a capo riga (interruzione di riga) subito dopo ogni tag Guide XML (di apertura e di chiusura), tranne che per i tag seguenti: <version>, <date>, <title>, <th>, <ti>, <li>, <i>, <e>, <uri>, <path>, <b>, <c>, <comment>, <mail>

Le righe vuote devono essere inserite subito dopo ogni <body> (solo tag di apertura) e prima di ogni <chapter>, <p>, <table>, <author> (set), <pre>, <ul>, <ol>, <warn>, <note> e <impo> (solo tag di apertura).

Il word-wrapping (a capo) deve essere applicato a 80 caratteri tranne dentro <pre>. Solo quando non c'è altra scelta, può essere cambiata questa regola (per esempio quando un URL eccede il massimo numero di caratteri): il redattore deve quindi andare a capo non appena c'è uno spazio. È fortemente consigliato tenere gli elementi del contenuto renderizzato all'interno di tag <pre> dentro le 80 colonne, per aiutare gli utenti che usano la console.

L'indentazione non deve essere usata, tranne con i costrutti XML i cui tag XML genitori sono <tr> (da <table>), <ul>, <ol>, <dl> e <author>. Se è usata la rientranza, essa deve essere costituita da 2 spazi. Ciò significa nessun carattere di tabulazione (<TAB>) e nessun ulteriore spazio. Le tabulazioni non devono essere presenti nei documenti GuideXML.

Nel caso in cui ci sia word-wrapping in <ti>, <th>, <li> o <dd>, è necessario indentare il contenuto

Un esempio di indentazione:

<table>
<tr>
  <th>Foo</th>
  <th>Bar</th>
</tr>
<tr>
  <ti>Questo è un esempio di indentazione</ti>
  <ti>
    Se il testo non può essere messo in una riga di 80 caratteri,
    dovete usare l'indentazione se il tag lo permette
  </ti>
</tr>
</table>

<ul>
  <li>Prima opzione</li>
  <li>Seconda opzione</li>
</ul>

Gli attributi non possono avere spazi tra il segno "=" e il loro valore. Un esempio:

Sbagliato :     <pre caption = "Attributi">
Corretto:     <pre caption="Attributi">

Stile di codifica esterno

Nelle tabelle (<table>) e negli elenchi (<ul> e <ol>) e <dl>, non bisogna utilizzare i punti ("."), a meno che non vi siano più frasi. In quel caso, ogni frase dovrebbe finire con una virgoletta (o con un altro carattere di interpunzione).

Ogni frase, incluse quelle nelle tabelle e negli elenchi, dovrebbe iniziare con una lettera maiuscola.

<ul>
  <li>Nessun punto</li>
  <li>Con punto. Frasi multiple..</li>
</ul>

I listati di codice dovrebbero avere sempre un titolo (caption).

Cercare di usare il più possibile <uri> con il link. In altre parole, si preferisce Forum Gentoo rispetto a http://forums.gentoo.org.

Quando si commenta qualcosa dentro a <pre>, usare <comment> e delle parentesi o il segno del commento per il linguaggio che si sta utilizzando (# per script bash e molte altre cose, // per codice C, etc.) Mettere il commento prima di ciò che si commenta.

(Sostituire "john" con il proprio nome utente)
# id john

6.  Risorse

Iniziare a scrivere

Il sistema GuideXML è stato progettato per essere "snello e significativo" affinché gli sviluppatori possano passare più tempo a scrivere documentazione e meno ad imparare la sintassi XML, con la speranza che questo permetterà agli sviluppatori che non sono "grandi scrittori" di cominciare a produrre documentazione di qualità per Gentoo. La guida Trucchi e consigli per lo sviluppo della documentazione potrebbe risultare molto interessante. Se si desidera dare una mano (o si ha qualche domanda in merito a GuideXML), inviare un messaggio alla mailing list gentoo-doc esponendo i propri pensieri. Buon divertimento!

I contenuti di questo documento sono rilasciati sotto la licenza Creative Commons - Attribution / Share Alike.