La sintassi "guide XML" è leggera ma espressiva, così che è facile da imparare, inoltre fornisce anche tutto ciò di cui hai bisogno per creare documentazione per il web. Il numero dei tags è 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 guide XML.

Prima di dare uno sguardo alla sintassi stessa, è utile conoscere come un documento XML è convertito in uno HTML. Per far questo, usiamo un file speciale chiamato guide.xsl, insieme con un XSLT processing tool (chiamato anche "engine"). Il file guide.xsl descrive esattamente come convertire il contenuto di un documento sorgento XML per creare un file destinazione HTML. Due popolari processori XSLT sono sabcmd (incluso nel package app-text/sablotron) e xsltproc (trovato nel package dev-libs/libxslt). Per esperienza, abbiamo travato che xsltproc è qualitativamente migliore ed è inoltre un processore XSLT ricco di features.

Una volta che hai installato xsltproc o sabcmd , sei pronto per convertire documenti XML in HTML. Sebbene, prima di fare questo, è necessario comunque prelevare l'ultimo snapshot del nostro albero web.

Il tarball gzipped del sito web può essere trovato qui.

Ora, estrai il tarball. Al suo interno, troverai una directory htdocs . Cerca il file htdocs/doc/<your lang>/gentoo-x86-install.xml (La nuova guida utente all'installazione). Questo sarà il nostro sorgente XML. La via più facile per eseguire la conversione è di cambiare la directory e di andare dove e situato il file guide.xsl . Quindi, eseguire xsltproc come segue:

# cd gentoo-web/xsl
# xsltproc guide.xsl ../doc/<your lang>/gentoo-x86-install.xml > /tmp/install.html

Se tutto è andato bene, dovresti avere una versione web-ready del file gentoo-x86-install.xml in /tmp/install.html. Per poter visualizzare correttamente questo documento con un web browser, dovrai copiare alcuni file da htdocs a /tmp, come css/main-new.css e (per essere sicuri) l'intera directory images .

Ora che sai come trasformare un documento XML, sei pronto per imparare la sintassi "guide XML". Comincieremo con il tag d'inizio usato in un documento "guide XML":

<?xml version='1.0' encoding="UTF-8"?>
<guide link="relative_link_to_your_guide">
<title>Gentoo Linux Documentation Guide</title>
<author title="Chief Architect"><mail link="drobbins@gentoo.org">
	Daniel Robbins</mail>
</author>
<author title="Editor"><mail link="thomasfl@gentoo.org">
	Thomas Flavel</mail>
</author>

<abstract>This guide shows you how to compose web documentation using
our new lightweight Gentoo guide XML syntax.  This syntax is the official
format for Gentoo Linux web documentation, and this document itself was created
using guide XML. </abstract>

<version>1.0</version>
<date>29 Mar 2001</date>

Nella prima linea, troviamo il tag che identifica questo come un documento XML. Di seguito, è presente un tag <guide> -- l'intero documento è racchiuso all'interno di una coppia di tags <guide> </guide> . C'è quindi un tag <title> , usato per definire il titolo dell'intero documento.

Arriviamo ai tags <author> , che contengono informazioni relative ai vari autori del documento. Ogni tag <author> accetta un elemento opzionale title= , usato per specificare la relazione tra l'autore e il documento (author, co-author, editor, etc.). In questo caso particolare, il nominativo dell'autore è racchiuso in un altro tag <mail> , usato per specificare un indirizzo email per questa persona. Il tag <mail> è opzionale è puo essere omesso, inoltre è richiesto non più di un elemento <author> per documento.

Incontriamo, in seguito, i tags <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 DD MMM YYYY). Questa serie di tags dovrebbe apparire all'inizio del documento. Ad eccezione dei tags <title> e <mail> , questi tags non dovrebbero apparire in nessun'altra parte, eccetto immediatamente dentro il tag <guide> , e per coerenza è raccomandato (ma non richiesto) che questi tags appaiano prima del contenuto del documento.

Una volta specificati i tags iniziali, sei pronto 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 aggiungi questo XML all'estratto precedente e termini il tutto con </guide> , avrai un valido (anche se minimo) documento:

<chapter>
<title>This is my chapter</title>
<section>
	<title>This is section one of my chapter</title>
	<body>
		<p>This is the actual text content of my section.</p>
	</body>
</section>
</chapter>

Sopra, abbiamo inserito il titolo del capitolo, aggiungendo un elemento <title> figlio dell'elemento <chapter> . Quindi, abbiamo creato una sezione, aggiungendo un elemento <section> . Se guardi all'interno dell'elemento <section> , vedrai due elementi figli -- un <title> ed un <body>. Mentre <title> non è nuovo, lo è <body> -- che contiene l'attuale testo all'interno di una data sezione. Daremo un'occhiata a quali tags sono permessi all'interno dell'elemento <body>.

è ora tempo di imparare come arricchire il contenuto corrente. Ecco un esempio di codice XML per l'elemento <body>:

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

<pre>
Questo è l'output.
# <i>questo è l'input dell'utente</i>

Rendi l' HTML/XML facile da leggere usando selective emphasis:
<foo><i>bar</i></foo>

<codenote>Ecco come inserire una nota in un blocco di codice</codenote>
</pre>
<note>Questa è una nota.</note>
<warn>Questo è un warning.</warn>
<impo>Questo è importante.</impo>

Ecco ora, come questo elemento <body> è disegnato:

Questo è un paragrafo. /etc/passwd è un file. http://www.gentoo.org è il mio website 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 usando selective emphasis:
<foo>bar</foo>

Ecco come inserire una nota in un blocco di codice

Abbiamo introdotto molti nuovi tags nella sezione precedente -- ecco cosa devi conoscere. I tags <p> (paragrafo), <pre> (blocco di codice), <note>, <warn> (warning) e <impo> (importante), posssono tutti contenere una o più linee di testo. Oltre l'elemento <table> (Che vedremo tra poco), ci sono tags che dovrebbero apparire immediatamente all'interno dell'elemento <body>. Un'altra cosa -- questi tags non dovrebbero essere impilati -- in altre parole, non mettere un elemento <note> all'interno di un elemento <p>. Come puoi indovinare, l'elemento <pre> preserva esattamente i suoi spazi, diventando un ottimo elemento per pezzi di codice.

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

L'elemento <path> è usato per marcare testo che si riferisce ad un file su disco -- sia un percorso assoluto che 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 input utente. Pensa a <c> come ad un modod di avvertire il lettore di qualcosa che se digitato esegue qualche tipo di azione. Per esempio, tutti i tags XML visibili in questo documento sono racchiusi tra elementi <c> perchè rappresentano qualcosa che l'utente potrebbe digitare . Usando elementi <c>, aiuterai i tuoi lettori a identificare facilmente i comandi che hanno bisogno di essere digitati. Poichè gli elementi <c> sono bilanciati da testo regolare, è raramente necessario delimitare l'input utente tra doppi apici. Per esempio, non riferirti ad un elemento "<c>" come ho fatto in questo momento. Evitando l'uso di doppi apici non necessari, rendiamo il documento più leggebile -- e adorabile!

<e> è usato per per dare enfasi ad una parola o ad una frase; per esempio: Dovrei usare realmente punti e virgola molto spesso. Come puoi vedere, questo testo è bilanciato dal paragrafo per dare enfasi. Questo ti aiuta a dare alle tue idee più forza!

Abbiamo dato un'occhiata al tag <mail> precedentemente; è usato per linkare del testo con un particolare indirizzo email, con la seguente sintassi <mail link="foo@bar.com">Mr. Foo Bar</mail>.

il tag <uri> è usato per puntare a files o indirizzi Internet. Assume due forme -- la prima può essere usata quando vuoi mostrare un URI nel corpo del testo, come questo link a http://www.gentoo.org. Per creare questo link, ho digitato <uri>http://www.gentoo.org</uri>. La forma alternativa è quando vuoi associare un URI con qualche altro testo -- per esempio, il website Gentoo Linux. Per creare questo link, ho digitato <uri link="http://www.gentoo.org">il website Gentoo Linux</uri>.

Ecco come inserire 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, Lttributo short= specifica una descrizione (usata correntemente per l'attributo alt= per le immagini HTML), e caption= specifica una leggenda. Non è troppo difficile :) è supportato anche il tag stile HTML <img src="foo.gif"/> per aggiungere immagini senza leggenda, bordi, ecc.

Così come in HTML, il sistema Guide supporta una sintassi semplificata per le tabelle. Per iniziare un tabella, usa un tag <table>. Comincia una riga con il tag <tr> . Tuttavia, per inserire i dati nella tabella, non supportiamo il tag HTML <td>; usiamo invece, <th> per inserire una intestazione, e <ti> per blocchi di inforrmazioni . Puoi usare <th> dovunque siano presenti <ti> -- non è richiesto che l'elemento <th> sia presente solo nella prima riga. Attualmente, questi tags non supportano alcun attributo, ma presto qualcuno sarà aggiunto (come l'attributo caption= per <table>).

Per creare liste ordinate e non, usa semplicemente i tags stile HTML <ol>, <ul> e <li>. I tags lista dovrebbero apparire solo all'interno dei tag <p>, <ti>, <note>, <warn> o <impo>.

è realmente semplice fare riferimento ad altre parti di un documento usando hyperlinks. Puoi creare un link che punti ad Capitolo 1 digitando <uri link="#doc_chap1">Capitolo 1</uri>. Per puntare alla Sezione 2 del Capitolo 1, digita <uri link="#doc_chap1_sect2">Sezione 2 del Capitolo 1</uri>. Per riferirsi alla Figura 3 nel Capitolo 1, digita <uri link="doc_chap1_fig3">figura 1.3</uri>. O, per riferirsi al Listato 2 nel Capitolo 2, type <uri link="doc_chap2_pre2">listato 2.2</uri>. Saranno aggiunte presto altre funzionalità (come il supporto alle tabelle).

Il sistema Guide è stato progettato per essere "magro e avaro" affinchè gli sviluppatori possano passare più tempo a scrivere documentazione e meno ad imparare la sintassi XML . Con la speranza, che questo permetterà gli sviluppatori che non sono "grandi scrittori" di cominciare a produrre documentazione di qualità per Gentoo Linux. Se ti piacerebbe aiutarci (o hai qualche domanda in merito), invia un messaggio alla gentoo-dev mailing list e alla gentoo-doc mailing list dichiarando cosa ti piacerebbe fare. Buon divertimento!