Gentoo XML Guide

1.Guide basics

Guide XML: obiettivi 

La sintassi Guide XML è leggera ma espressiva, così che è facile da imparare, inoltre fornisce anche tutto ciò di cui avete 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.

Ulteriori risorse 

Se state progettando di contribuire alla documentazione di Gentoo, o desiderate provare Guide XML, leggete la Tips and Tricks, che contiene consigli e trucchi per lo sviluppo della documentazione.

Si potrebbe volere guardare il sorgente XML di questo documento mentre state leggendo.

2.Guide XML

Struttura di base 

Si parte con l'imparare la sintassi Guide XML. Cominceremo 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/en/guide.xml" lang="en">
<title>Gentoo Documentation Guide</title>

<author title="Author">
  <mail link="yourname@gentoo.org">Your Name</mail>
</author>

<abstract>
This guide shows you how to compose web documentation using
our new lightweight Gentoo GuideXML syntax.  This syntax is the official
format for Gentoo web documentation, and this document itself was created
using GuideXML.
</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>29 Mar 2001</date>

Nella prima linea, troviamo il tag che identifica questo come un documento XML e specifica il DTD. La riga <!-- $Header$ --> sarà modificata dal server CVS e aiuta a sapere il numero delle revisioni. Di seguito, è presente un tag <guide> -- l'intero documento è racchiuso all'interno di una coppia di tags <guide> </guide>. Un attributo link è obbligatorio e dovrebbe contenere il percorso assoluto al documento relativamente al documento root anche se il filename funziona da solo. E' usato per generare un link a una versione facilmente stampabile del documento. Se si usa un valore sbagliato, il link alla versione facilmente stampabile non funzionerà o punterà a un documento sbagliato. I documenti tradotti devono specificare il percorso completo perchè è usato anche per controllare se il documento originale è più recente. Un attributo lang dovrebbe essere usato per specificare la lingua del codice del documento. E' usato per formattare la data e inserire "Note", "Content", etc. nella lingua specificata. Quella di default è inglese.

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 e 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 YYYY-MM-DD). Date non valide o non nel formato YYYY-MM-DD appariranno lo stesso con il formato sbagliato.

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.

Infine abbiamo il tag <license/>, usato per pubblicare il documento sotto la licenza Creative Commons - Attribution / Share Alike, come richiesto dalla Documentation Policy.

Capitoli e sezioni 

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

<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, abbiamo inserito il titolo del capitolo, aggiungendo un elemento <title> figlio dell'elemento <chapter> . Quindi, abbiamo creato una sezione, aggiungendo un elemento <section> . Se guardate all'interno dell'elemento <section> , vedrete 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>.

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 website 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 usando selective emphasis:
<foo><i>bar</i></foo>

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

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

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

<impo>
Questo è importante.
</impo>

Ecco ora, come l'elemento <body> sotto è disegnato:

Questo è un paragrafo. /etc/passwd è un file. http://forums.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)

I tags <body> 

Abbiamo introdotto molti nuovi tags nella sezione precedente -- ecco cosa dovete conoscere. I tags <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 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 mettete un elemento <note> all'interno di un elemento <p>. Come potete indovinare, l'elemento <pre> preserva esattamente i suoi spazi, diventando un ottimo elemento per pezzi di codice. Si deve nominare il tag <pre> con un attributo caption:

<pre caption = "Output of 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 Contented. Thomas Jefferson e Benjamin Franklin sono stati due artefici della Dichiarazione di Indipendenza. Franklin ha scoperto l'elettricità lucidando due gatti e ha dichiarato "Un cavallo diviso non può stare in piedi" Franklin è morto nel 1790 ed è ancora morto.

Le epigrafi a volte sono usate all'inizio dei capitoli per mostrare 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...

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

Gli elementi <path>, <c>, <b>, <e>, <sub> e <sup> possono essere usati all'interno del tag <body>, ad eccezione di <pre>. L'elemento <i> può essere solo usato dentro <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. Pensate a <c> come ad un modo 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>, aiuterete i vostri 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 riferitevi ad un elemento "<c>" come ho fatto in questo momento. Evitando l'uso di doppi apici non necessari, rendiamo il documento più leggibile -- e simpatico!

Quando si desidera evidenziare un qualche testo come input di utente dentro <pre>, usate invece <i>.

<b> è usato per scrivere in neretto una parte di testo.

<e> è usato per per dare enfasi ad una parola o ad una frase; per esempio: Dovrei usare realmente punti e virgola molto spesso. Come potete vedere, questo testo è bilanciato dal paragrafo per dare enfasi. Questo vi aiuta a rafforzare le vostre idee!

<sub> e <sup> sono usati per specificare subscript e superscript.

<mail> e <uri> 

Abbiamo precedentemente dato un'occhiata al tag <mail>; è usato per linkare del testo con un particolare indirizzo email, con la seguente sintassi <mail link="foo@bar.com">Mr. Foo Bar</mail>. Se si vuole visualizzare l'indirizzo email, si può usare <mail>foo@bar.com</mail>, e sarà visualizzato come foo@bar.com.

Il tag <uri> è usato per puntare a files o indirizzi Internet. Assume due forme -- la prima può essere usata quando volete mostrare un URI nel corpo del testo, come questo link a http://forums.gentoo.org. Per creare questo link, ho digitato <uri>http://forums.gentoo.org</uri>. La forma alternativa è quando volete associare un URI con qualche altro testo -- per esempio, Forum Gentoo. Per creare questo link, ho digitato <uri link="http://forums.gentoo.org"> Forum Gentoo</uri>. Non si deve scrivere http://www.gentoo.org/ per linkare altre parti del sito web di Gentoo. Per esempio, un link a documentation main index dovrebbe essere <uri link="/doc/en/index.xml">documentation main index</uri>. Si può omettere index.xml quando ci si collega a una directory index, per esempio, <uri link="/doc/en/">documentation main index</uri>.

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 leggenda. Non è troppo difficile :) E' supportato anche il tag stile HTML <img src="foo.gif"/> per aggiungere immagini senza leggenda, bordi, ecc.

Tabelle 

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 informazioni . Potete usare <th> dovunque siano presenti <ti> -- non è richiesto che l'elemento <th> sia presente solo nella prima riga.

Il tag per la tabella (<th>) accetta gli attributi colspan e rowspan per misurare i titoli tra le righe, le colonne o entrambi, come mostrato sotto:

Liste 

Per creare liste ordinate e non, usate semplicemente i tags stile XHTML <ol>, <ul> e <li>. I tags lista dovrebbero apparire solo all'interno dei tag <body>, <li> ed è possibile avere liste dentro liste. Si devono chiudere i tag anche quelli delle liste (requisito generale XML), non come HTML.

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

La seguente lista copiata da w3.org mostra che una definizione di lista contiene liste ordinate e non. Non potrebbe contenere un'altra definizione di lista.

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

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

Riferimenti Intra-document 

E' realmente semplice fare riferimento ad altre parti di un documento usando hyperlinks. Potete creare un link che punti ad Capitolo 1 digitando <uri link="#doc_chap1">Capitolo 1</uri>. Per puntare alla Sezione 2 del Capitolo 1, digitate <uri link="#doc_chap1_sect2">Sezione 2 del Capitolo 1</uri>. Per riferirsi alla Figura 3 nel Capitolo 1, digitate <uri link="#doc_chap1_fig3">figure 1.3</uri>. O, per riferirsi al Listato 2 nel Capitolo 2, digitate <uri link="#doc_chap2_pre2">code listing 2.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 disclaimer predefinito all'inizio del documento. I disclaimer disponibili sono:

• articles è usato per 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 potrebbe aggiungere un link alla nuova versione. Ci serve l'attributo redirect. L'utente è reindirizzato alla nuova pagina.

<?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 Installation Guide</title>

<author title="Author">
...

3.Stile di codifica

Introduzione 

E' necessario uno stile di codifica, poichè tutta la documentazione di Gentoo è un lavoro fatto in comune tra molte persone che potranno cambiare la documentazione esistente. Uno stile di codifica contiene due sezioni. La prima riguarda la codifica interna, come sono messi i tag xml. La seconda riguarda il contenuto, come non confondere il lettore.

Descriviamo le due sezioni.

Stile di codifica interno 

Le nuove righe devono essere inserite subito dopo ogni tag Guide XML (di apertura e di chiusura), tranne per: <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).

Word-wrapping 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 sistemare ogni volta che c'è uno spazio. Si dovrebbe provare a tenere gli elementi del contenuto rendered di <pre> dentro le 80 colonne, per aiutare gli utenti che usano la console.

La rientranza non deve essere usata, tranne con la struttura XML della quale i tag XML genitori sono <tr> (da <table>), <ul>, <ol>, <dl> e <author>. Se è usata la rientranza, ci devono essere due spazi per ognuna. Ciò significa nessuna tabs e nessun'altri spazi. I tab non ci devono essere nei documenti GuideXML.

Nel caso in cui ci sia word-wrapping in <ti>, <th>, <li> o <dd>, la rientranza deve essere usata per il contenuto.

Un esempio per la rientranza:

<table>
<tr>
  <th>Foo</th>
  <th>Bar</th>
</tr>
<tr>
  <ti>Questo è un esempio per la rientranza</ti>
  <ti>
    Se il testo non può essere messo in una riga di 80 caratteri, 
    si deve usare la rientranza 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>, le virgolette (".") non dovrebbero essere usate, a meno che non vi siano frasi ripetute. In quel caso, ogni frase dovrebbe finire con una virgoletta (o con un altro segno di lettura).

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

<ul>
  <li>Senza virgoletta</li>
  <li>Con virgoletta. Frasi ripetute</li>
</ul>

Gli elenchi di codifica dovrebbero avere sempre un titolo.

Cercate di usare il più possibile <uri> con il link. In altre parole, è preferito Forum Gentoo su http://forums.gentoo.org.

Quando commentate qualcosa dentro a <pre>, usate <comment> e parentesi o il segno del commento per il linguaggio che si è usato (# per script bash e molte altre cose, // per codice C, etc.) Mettete il commento prima del soggetto del commento.

(Sostituite "john" con il vostro user name)
# id john

4.Formato del manuale

Guida o Manuale 

Per una grande quantità di documentazione come l'Installazione di Gentoo, è stato necessario ampliare il formato. Abbiamo progettato un formato compatibile con Guide XML, che ci permettesse di scrivere la documentazione modulare e multi-pagina.

File principale 

Il primo cambiamento è stato dettato dalla necessità di un documento "primario". Questo documento non contiene testo ma solo i riferimenti ai moduli individuali della documentazione. La sintassi non cambia molto da Guide XML:

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

<book link="example.xml">
<title>Esempio di uso del 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>

Finora nessuna differenza sostanziale (tranne <book> invece di <guide>). Non si inizia con <chapter>, ma con <part>, che è uguale all'avere una parte separata in un manuale:

<part>
<title>Prima parte</title>
<abstract>
...
</abstract>

(Definire i molti capitoli)
</part>

Ogni parte è accompagnata da un <title> e un <abstract> che serve per una breve introduzione.

All'interno di ogni parte, si definisce ogni <chapter>. Ogni capitolo deve essere un documento separato. Non è una sorpresa l'aggiunta di un tag speciale (<include>) che permette di includere il documento separato.

<chapter>
<title>Primo capitolo</title>
<abstract>
 Questa è una piccola spiegazione sul primo capitolo.
</abstract>

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

</chapter>

Progettazione dei capitoli 

Il contenuto di un capitolo è strutturato come segue:

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

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

</sections>

In ogni capitolo si possono definire <section> (equivalente di <chapter> in una Guida), e <subsection> (equivalente di <section> in una Guida).

Ogni capitolo dovrebbe avere gli elementi data e versione. Ultima data di tutti i capitoli e del documento principale sarà visualizzata quando un utente vede tutte le parti del manuale.

5.Risorse

Iniziare a scrivere 

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à agli sviluppatori che non sono "grandi scrittori" di cominciare a produrre documentazione di qualità per Gentoo. Si può essere interessati a Documentation Development Tips & Tricks. Se vi piacerebbe aiutarci (o avete qualche domanda in merito), inviate un messaggio alla gentoo-doc mailing list dichiarando cosa vi piacerebbe fare. Buon divertimento!