Go to:
Gentoo Home
Documentation
Forums
Lists
Bugs
Planet
Store
Wiki
Get Gentoo!
Gentoo's Bugzilla – Attachment 141828 Details for
Bug 207575
[it] Updated translation of xml-guide.xml
Home
|
New
–
[Ex]
|
Browse
|
Search
|
Privacy Policy
|
[?]
|
Reports
|
Requests
|
Help
|
New Account
|
Log In
[x]
|
Forgot Password
Login:
[x]
Updated xml-guide.xml from Ver 7 Rev 1.66 to Ver 8 Rev 1.67.
xml-guide.xml (text/plain), 40.49 KB, created by
Gianni Costanzi
on 2008-01-26 16:50:18 UTC
(
hide
)
Description:
Updated xml-guide.xml from Ver 7 Rev 1.66 to Ver 8 Rev 1.67.
Filename:
MIME Type:
Creator:
Gianni Costanzi
Created:
2008-01-26 16:50:18 UTC
Size:
40.49 KB
patch
obsolete
><?xml version = "1.0" encoding = "UTF-8"?> ><!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> ><!-- $Header: /var/www/viewcvs.gentoo.org/raw_cvs/gentoo/xml/htdocs/doc/it/xml-guide.xml,v 1.29 2007/08/08 11:24:58 scen Exp $ --> > ><guide link="/doc/it/xml-guide.xml" lang="it"> ><title>Guida a Gentoo XML</title> > ><author title="Autore"> > <mail link="neysx">Xavier Neys</mail> ></author> ><author title="Autore"> > <mail link="drobbins@gentoo.org">Daniel Robbins</mail> ></author> ><author title="Autore"> ><!-- zhen@gentoo.org -->John P. Davis ></author> ><author title="Redazione"> > <mail link="peesh@gentoo.org">Jorge Paulo</mail> ></author> ><author title="Redazione"> > <mail link="swift@gentoo.org">Sven Vermeulen</mail> ></author> ><author title="Traduzione"> > <mail link="stefano.mazzone@tin.it">Stefano Mazzone</mail> ></author> ><author title="Traduzione"> > Stefano Rossi ></author> ><author title="Traduzione"> > <mail link="gianni.costanzi@gmail.com">Gianni Costanzi</mail> ></author> ><author title="Traduzione"> > Team Italiano ></author> > ><abstract> >Questa guida mostra come produrre documentazione web utilizzando la nuova e >leggera sintassi Gentoo Guide XML. Questa sintassi è il formato ufficiale per la >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>8</version> ><date>2007-10-04</date> > ><chapter> ><title>I fondamenti di Guide XML</title> ><section> ><title>Guide XML: obiettivi</title> ><body> > ><p> >La sintassi Guide XML è 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. ></p> > ><p> >L'obiettivo è di <e>creare</e> e <e>convertire</e> facilmente documenti Guide >XML. ></p> > ></body> ></section> ><section> ><title>Ulteriori risorse</title> ><body> > ><p> >Se si desidera contribuire alla documentazione di Gentoo, o se si vuole provare >Guide XML, leggere la guida <uri >link="/proj/it/gdp/doc/doc-tipsntricks.xml">Trucchi e consigli per lo sviluppo >della documentazione</uri>, che contiene consigli e trucchi per lo sviluppo di >documentazione. ></p> > ><p> >à possibile guardare il <uri link="?passthru=1">sorgente XML</uri> di questo >stesso documento mentre lo si sta leggendo. ></p> > ></body> ></section> ></chapter> > ><chapter> ><title>Guide XML</title> ><section> ><title>Struttura di base</title> ><body> > ><p> >La prima cosa da fare è imparare la sintassi Guide XML. Si comincerà con il tag >d'inizio usato in un documento Guide XML: ></p> > ><pre caption="La parte iniziale di un documento Guide XML" > ><?xml version="1.0" encoding="UTF-8"?> ><!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> ><!-- $Header$ --> > ><guide link="<i>/doc/it/guide.xml</i>" lang="<i>it</i>"> ><title><i>Guida alla Documentazione Gentoo</i></title> > ><author title="<i>Autore</i>"> > <mail link="<i>tuonome@gentoo.org</i>"><i>Tuo Nome</i></mail> ></author> > ><abstract> ><i>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.</i> ></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><i>1.0</i></version> ><date><i>2001-03-29</i></date> ></pre> > ><p> >Nelle prime linee, c'è il tag che identifica il documento come un documento XML >e ne specifica il DTD. La riga <c><!-- $Header$ --></c> sarà >modificata dal server CVS e serve per tenere traccia del numero delle revisioni. >Segue il tag <c><guide></c>: l'intero documento è racchiuso all'interno di >una coppia di tag <c><guide> </guide></c>. ><br/> >L'attributo <c>link</c> è 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 principalmente per generare >un link ad una versione facilmente stampabile del documento e oer 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 vengaprocessato in un altro modo. ><br/> >L'attributo <c>lang</c> dovrebbe essere utilizzato per specificare il codice del >linguaggio del documento. Esso è utilizzato performattare la data e per inserire >le stringhe come "<e>Nota</e>", "<e>Indice</e>", etc. nel linguaggio corretto. >Il linguaggio di default è l'inglese. ></p> > ><p> >Segue un tag <c><title></c>, usato per definire il titolo dell'intero >documento. ></p> > ><p> >Si arriva ai tag <c><author></c>, che contengono informazioni relative ai >vari autori del documento. Ogni tag <c><author></c> accetta un elemento >opzionale <c>title</c>, 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 <c><mail></c>, usato per >specificare un indirizzo email relativo all'autore. Il tag <c><mail></c> è >opzionale e può essere omesso mentre è necessario almeno un tag ><c><author></c> per documento. ></p> > ><p> >Successivamento si trovano i tag <c><abstract></c>, <c><version></c> >e <c><date></c>, 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. ></p> > ><p> >Questo riassume i tag che dovrebbero apparire all'inizio di un documento di >guida. Insieme ai tag <c><title></c> e <c><mail></c>, questi tag >dovrebbero apparire immediatamente dentro il tag <c><guide></c> 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. ></p> > ><p> >Infine c'è il tag <c><license/></c>, usato per pubblicare il documento >sotto la licenza <uri >link="http://creativecommons.org/licenses/by-sa/2.5/">Creative Commons - >Attribution / Share Alike</uri>, come richiesto dalla <uri >link="/proj/it/gdp/doc/doc-policy.xml">Politica della Documentazione di Gentoo >Linux</uri>. ></p> > ></body> ></section> ><section> ><title>Capitoli e sezioni</title> ><body> > ><p> >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'<uri link="#doc_chap2_pre1">esempio >precedente</uri> e si termina il tutto con <c></guide></c>, si otterrà un >documento valido (anche se minimale): ></p> > ><pre caption="Esempio minimale della guida"> ><chapter> ><title><i>Questo è il mio capitolo</i></title> ><section> ><title><i>Questa è la sezione del mio capitolo</i></title> ><body> > ><p> ><i>Questo è il paragrafo della mia sezione.</i> ></p> > ></body> ></section> ></chapter> ></pre> > ><p> >Sopra, è stato inserito il titolo del capitolo, aggiungendo un elemento ><c><title></c> figlio dell'elemento <c><chapter></c>. Quindi, è >stato creato una sezione, aggiungendo un elemento <c><section></c>. >Guardando all'interno dell'elemento <c><section></c> si vedranno due >elementi figli: <c><title></c> e <c><body></c>. Mentre ><c><title></c> non è nuovo, lo è <c><body></c>, che contiene >l'attuale testo all'interno di una data sezione. Si vedranno ora quali tag sono >permessi all'interno dell'elemento <c><body></c>. ></p> > ><note> >Un elemento <c><guide></c> deve contenere almeno un elemento ><c><chapter></c>; un elemento <c><chapter></c> deve contenere >almeno un elemento <c><section></c>; un elemento <c><section></c> >deve contenere almeno un elemento <c><body></c>. ></note> > ></body> ></section> ><section> ><title>Un esempio di <body></title> ><body> > ><p> >E' tempo di imparare ad arricchire il contenuto della guida. Ecco un esempio di >codice XML per l'elemento <c><body></c>: ></p> > ><pre caption="Esempio di codice per 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> ></pre> > ><p> >Ecco ora, come appare l'elemento <c><body></c> dell'esempio qui sopra: ></p> > ><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="Esempio di codice"> >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> > ></body> ></section> ><section> ><title>I tag <body></title> ><body> > ><p> >Sono stati introdotti molti nuovi tag nella sezione precedente, ecco quello che >è necessario sapere. I tag <c><p></c> (paragrafo), <c><pre></c> >(blocco di codice), <c><note></c>, <c><warn></c> (warning) e ><c><impo></c> (importante), possono tutti contenere una o più linee di >testo. Oltre l'elemento <c><table></c>, <c><ul></c>, ><c><ol></c> e <c><dl></c> (che verranno analizzati tra poco), ci >sono tag che dovrebbero apparire immediatamente all'interno dell'elemento ><c><body></c>. Inoltre, questi tag <e>non dovrebbero</e> essere innestati: >in altre parole, non mettere un elemento <c><note></c> all'interno di un >elemento <c><p></c>. Come si potrà facilmente indovinare, l'elemento ><c><pre></c> preserva esattamente i suoi spazi, diventando un ottimo >elemento per blocchi di codice. In questo casi bisogna specificare un attributo ><c>caption</c> per il tag <c><pre></c>: ></p> > ><pre caption="Definire <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> ></pre> > ></body> ></section> ><section> ><title>Epigrafi</title> ><body> > ><p by="Studente anonimo"> >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. ></p> > ><p> >Le epigrafi a volte sono usate all'inizio dei capitoli per introdurre quello che >segue. E' un semplice paragrafo con un attributo <c>by</c> che contiene la >frase. ></p> > ><pre caption="Breve epigrafo"> ><p by="Studente anonimo"> >I delegati dei 13 stati originali hanno formato... ></p> ></pre> > ></body> ></section> ><section> ><title> > <path>, <c>, <b>, <e>, <sub> e <sup> ></title> ><body> > ><p> >Gli elementi <c><path></c>, <c><c></c>, <c><b></c>, ><c><e></c>, <c><sub></c> e <c><sup></c> possono essere usati >all'interno di ogni tag figlio del tag <c><body></c>, ad eccezione di ><c><pre></c>. ></p> > ><p> >L'elemento <c><path></c> è usato per marcare testo che si riferisce ad un ><e>file su disco</e>, sia esso un percorso <e>assoluto</e> o <e>relativo</e>, o ><e>semplicemente un nome di file</e>. Questo elemento è generalmente >rappresentato con un font monospaced per differenziarlo dal tipo standard >utilizzato nel paragrafo. ></p> > ><p> >L'elemento <c><c></c> è usato per marcare un <e>comando</e> o l'<e>input >dell'utente</e>. Pensare a <c><c></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><c></c> perché rappresentano qualcosa che l'utente potrebbe digitare. >Usando elementi <c><c></c>, si aiuteranno i propri lettori ad identificare >facilmente i comandi che hanno bisogno di essere digitati. Poiché gli elementi ><c><c></c> sono distinti dal testo regolare, <e>è raramente necessario >delimitare l'input utente tra doppi apici</e>. Per esempio, non fare riferimento >ad un elemento "<c><c></c>" come viene fatto in questa frase. Evitando >l'uso di doppi apici non necessari, si rende il documento più leggibile.. e >carino! ></p> > ><p> >Come si potrà immaginare, <c><b></c> è usato per scrivere in ><b>grassetto</b> una parte di testo. ></p> > ><p> ><c><e></c> è usato per per dare enfasi ad una parola o ad una frase. Ad >esempio: dovrei utilizzare punti e virgola <e>veramente</e> più spesso. Come si >può vedere, questo testo è distinto dal resto del paragrafo per dare enfasi. >Questo aiuta a rafforzare le proprie idee! ></p> > ><p> ><c><sub></c> e <c><sup></c> sono usati per specificare ><sub>subscript</sub> e <sup>superscript</sup>. ></p> > ></body> ></section> ><section> ><title>Esempi di codice e codice colorato</title> ><body> > ><p> >Per migliorare la leggibilità degli esempi di codice, i tag seguenti sono >consentiti all'interno di blocchi <c><pre></c>: ></p> > ><dl> > <dt><c><i></c></dt> > <dd>Distingue l'input dell'utente dal testo visualizzato</dd> > <dt><c><comment></c></dt> > <dd>Commenti relativi alle azioni che seguono il commento</dd> > <dt><c><keyword></c></dt> > <dd> > Denota una parola chiave nel linguaggio utilizzato all'interno dell'esempio > di codice > </dd> > <dt><c><ident></c></dt> > <dd>Utilizzato per un identificatore</dd> > <dt><c><const></c></dt> > <dd>Utilizzato per una costante</dd> > <dt><c><stmt></c></dt> > <dd>Utilizzato per uno statement</dd> > <dt><c><var></c></dt> > <dd>Utilizzato per una variabile</dd> ></dl> > ><note> >Ricordarsi che tutti gli spazi precedenti e seguenti e tutte le interruzioni di >linea all'interno dei blocchi <c><pre></c> appariranno nella pagina html >risultante. ></note> > ><p> >Esempio di blocco <c><pre></c> con codice colorato: ></p> > ><pre caption="La mia prima ebuild"> ><comment># Copyright 1999-2006 <b>Gentoo Foundation</b> ># Distributed under the terms of the GNU General Public License v2 ># $Header: $</comment> > ><ident>DESCRIPTION</ident>=<const>"Exuberant ctags generates tags files for quick source navigation"</const> ><ident>HOMEPAGE</ident>=<const>"http://ctags.sourceforge.net"</const> ><ident>SRC_URI</ident>=<const>"mirror://sourceforge/ctags/<var>${P}</var>.tar.gz"</const> > ><ident>LICENSE</ident>=<const>"GPL-2"</const> ><ident>SLOT</ident>=<const>"0"</const> ><ident>KEYWORDS</ident>=<const>"~mips ~sparc ~x86"</const> ><ident>IUSE</ident>=<const>""</const> > ><stmt>src_compile()</stmt> { > <keyword>econf</keyword> --with-posix-regex || <keyword>die</keyword> <const>"econf failed"</const> > <keyword>emake</keyword> || <keyword>die</keyword> <const>"emake failed"</const> >} > ><stmt>src_install()</stmt> { > <keyword>make</keyword> <ident>DESTDIR</ident>="<var>${D}</var>" install || <keyword>die</keyword> <const>"install failed"</const> > > <keyword>dodoc</keyword> FAQ NEWS README > <keyword>dohtml</keyword> EXTENDING.html ctags.html >} ></pre> > ></body> ></section> > ><section> ><title><mail> e <uri></title> ><body> > ><p> >Precedentemente si è visto il tag <c><mail></c>; è usato per collegare del >testo con un particolare indirizzo email, con la seguente sintassi <c><mail >link="foo.bar@example.com">Mr. Foo Bar</mail></c>. Se si vuole >visualizzare l'indirizzo email, è possibile usare ><c><mail>foo.bar@example.com</mail></c>, e sarà visualizzato come ><mail> foo.bar@example.com</mail>. ></p> > ><p> >Alcune forme abbreviate facilitano l'utilizzo di nomi edemail degli sviluppatori >di Gentoo. Sia <c><mail>neysx</mail></c> che <c><mail >link="neysx"/></c> appariranno come <mail>neysx</mail>. Se si vuole >utilizzare l'email di uno sviluppatore di Gentoo senza mostrare nome e cognome >utilizzare la seconda forma specificando il contenuto da mostrare. Ad esempio, >per mostrate solo il nome dello sviluppatore: <c><mail >link="neysx">Xavier</mail></c> appare come <mail >link="neysx">Xavier</mail>. ><br/> >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. ></p> > ><p> >Il tag <c><uri></c> è 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 <uri>http://forums.gentoo.org/</uri>. Per >creare questo link, è stato digitato ><c><uri>http://forums.gentoo.org/</uri></c>. Utilizzare la forma >alternativa quando si vuole associare un URI con qualche altro testo, per >esempio, <uri link="http://forums.gentoo.org/" >Forum Gentoo</uri>. Per creare ><e>questo</e> link, è stato digitato <c><uri >link="http://forums.gentoo.org/">Forum Gentoo</uri></c>. Non è >necessario scrivere <c>http://www.gentoo.org/</c> per collegare altre parti del >sito web di Gentoo. Per esempio, un collegamento a <uri >link="/doc/it/">Documentazione Gentoo</uri> dovrebbe essere semplicemente >definito con <c><uri link="/doc/it/index.xml">Documentazione >Gentoo</uri></c>. à possibile omettere anche <c>index.xml</c> quando si >crea un collegamento a una directory indice, per esempio, <c><uri >link="/doc/it/">Documentazione Gentoo</uri></c>. Scrivere la slash >finale risparmia una richiesta HTTP aggiuntiva. ></p> > ><p> >Non si dovrebbe utilizzare un tag <c><uri></c> un un attributo <c>link</c> >che incomincia con <c>mailto:</c>. In questo caso utilizzare un tag <c><mail></c>. ></p> > ><p> >Si prega di evitare la sindrome da <uri >link="http://en.wikipedia.org/wiki/Click_here">clicca qui ></uri> come raccomandato dal <uri >link="http://www.w3.org/QA/Tips/noClickHere">W3C</uri>. ></p> > ></body> ></section> ><section> ><title>Figure</title> ><body> > ><p> >Ecco come inserire una figura in un documento: <c><figure link="mygfx.png" >short="la mia figura" caption="la mia figura preferita "/></c>. L'attributo ><c>link</c> punta all'attuale immagine grafica, l'attributo <c>short</c> >specifica una descrizione (usata correntemente per l'attributo <c>alt</c> per le >immagini HTML), e <c>caption</c> specifica una didascalia. Nulla di troppo >difficile :) E' supportato anche il tag HTML <img src="foo.gif"/> per >aggiungere immagini senza didascalia, bordi, ecc. ></p> > ></body> ></section> ><section> ><title>Tabelle</title> ><body> > ><p> >Così come in HTML, il sistema GuideXML supporta una sintassi semplificata per le >tabelle. Per iniziare un tabella, usare un tag <c><table></c>. Cominciare >una riga con il tag <c><tr></c>. Tuttavia, per inserire i dati nella >tabella, <e>non</e> è supportato il tag HTML <td>; si utilizza, invece, ><c><th></c> per inserire una intestazione, e <c><ti></c> per blocchi >di informazioni. Si può usare <c><th></c> ovunque sia possibile utilizzare >il tag <c><ti></c>, non è richiesto che l'elemento <c><th></c> sia >presente solo nella prima riga. ></p> > ><p> >Inoltre, sia le intestazioni delle tabelle (<c><th></c>) che gli elementi >(<c><ti></c>) delle tabelle accettano gli attributi <c>colspan</c> e ><c>rowspan</c> per estendere il loro contenuto su più righe, colonne o entrambe. ></p> > ><p> >Inoltre, gli elementi della tabella (<c><ti></c>) possono avere un >allineamento sulla destra o al centro tramite l'attributo <c>align</c>. Le >intestazioni delle tabelle (<c><th></c>) sono centrate automaticamente. ></p> > ><table> ><tr> > <th colspan="4">Questo titolo si estende su 4 colonne</th> ></tr> ><tr> > <th rowspan="6">Questo titolo si estende su 6 righe</th> > <ti>Item A1</ti> > <ti>Item A2</ti> > <ti>Item A3</ti> ></tr> ><tr> > <ti align="center">Item B1</ti> > <th colspan="2" rowspan="2">Titolo in un blocco 2x2</th> ></tr> ><tr> > <ti align="right">Item C1</ti> ></tr> ><tr> > <ti colspan="3" align="center">Item D1..D3</ti> ></tr> ><tr> > <ti rowspan="2">Item E1..F1</ti> > <ti colspan="2" align="right">Item E2..E3</ti> ></tr> ><tr> > <ti colspan="2" align="right">Item F2..F3</ti> ></tr> ></table> > ></body> ></section> ><section> ><title>Liste</title> ><body> > ><p> >Per creare liste ordinate e non, usare semplicemente i tag stile XHTML ><c><ol></c>, <c><ul></c> e <c><li></c>. I tag lista dovrebbero >apparire solo all'interno dei tag <c><body></c> e <c><li></c>, 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. ></p> > ><p> >Sono supportate le definizioni di liste (<c><dl></c>). Nè il tag di >definizione del termine, (<c><dt></c>) nè il tag di definizione dei >dati (<c><dd></c>) accettano altri tag di paragrafi o note. Una >definizione di lista comprende ></p> > ><dl> > <dt><c><dl></c></dt> > <dd>Un tag di <b>D</b>efinizione <b>L</b>ista contentente</dd> > <dt><c><dt></c></dt> > <dd>coppie di tag <b>D</b>efinizione-<b>T</b>ermine</dd> > <dt><c><dd></c></dt> > <dd>e <b>D</b>efinizione-<b>D</b>ati</dd> ></dl> > ><p> >La seguente lista copiata da <uri >link="http://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> mostra >come una definizione di lista possa contenere liste ordinate e non. Non può >invece contenere un'altra definizione di lista. ></p> > ><dl> > <dt><b>Ingredienti:</b></dt> > <dd> > <ul> > <li>100 g. di farina</li> > <li>10 g. di zucchero</li> > <li>1 tazzina di acqua</li> > <li>2 uova</li> > <li>sale, pepe</li> > </ul> > </dd> > <dt><b>Procedura:</b></dt> > <dd> > <ol> > <li>Mischiare gli ingredienti</li> > <li>Versare gli ingredienti bagnati</li> > <li>Mischiare per 10 minuti</li> > <li>Cuocere per 1 ora a 300 gradi</li> > </ol> > </dd> > <dt><b>Note:</b></dt> > <dd>La ricetta può essere migliorata aggiungendo uva passa</dd> ></dl> > ></body> ></section> ><section> ><title>Riferimenti interni al documento</title> ><body> > ><p> >GuideXML rende veramente semplice fare riferimento ad altre parti di un documento usando >collegamenti ipertestuali (hyperlinks). à possibile creare un collegamento che >punti a <uri link="#doc_chap1" >Capitolo 1</uri> digitando <c><uri >link="#doc_chap1">Capitolo 1</uri></c>. Per puntare alla <uri >link="#doc_chap1_sect2" >Sezione 2 del Capitolo 1</uri>, digitare <c><uri >link="#doc_chap1_sect2">Sezione 2 del Capitolo 1</uri></c>. Per >riferirsi alla Figura 3 nel Capitolo 1, digitare <c><uri >link="#doc_chap1_fig3">Figura 1.3</uri></c>. O, per riferirsi al <uri >link="#doc_chap2_pre2" >Listato 2 nel Capitolo 2</uri>, digitare <c><uri >link="#doc_chap2_pre2">Listato 2 nel Capitolo 2</uri></c>. ></p> > ><p> >Tuttavia, alcune guide cambiano spesso, e vi possono essere alcuni link non più >esatti. Per evitare questo, si può definire un nome per un ><c><chapter></c>, <c><section></c> o <c><tr></c> usando >l'attributo <c>id</c>, e poi puntare a esso, così: ></p> > ><pre caption="Usare l'attributo id"> ><chapter id="foo"> ><title>Questo è foo!</title> >... ><p> >Ulteriori informazioni possono essere trovate nel ><uri link="#foo">foo chapter</uri> ></p> ></pre> > ></body> ></section> ><section> ><title>Disclaimer e documenti obsoleti</title> ><body> > ><p> >Può essere applicato un attributo <c>disclaimer</c> alle guide e ai manuali per >visualizzare un disclaimer predefinito all'inizio del documento. I disclaimer >disponibili sono: ></p> > ><ul> > <li> > <b>articles</b> è usato per gli <uri link="/doc/it/articles/">articoli > ripubblicati</uri> > </li> > <li> > <b>draft</b> è usato per indicare un documento che è ancora in lavorazione e > che non dovrebbe essere considerato ufficiale > </li> > <li> > <b>oldbook</b> è usato su vecchi manuali per indicare che non sono più > mantenuti > </li> > <li><b>obsolete</b> è usato per indicare che un documento è obsoleto</li> ></ul> > ><p> >Quando si afferma che un documento è obsoleto, si può aggiungere un collegamento >alla nuova versione. Ciò che serve in questo caso è l'attributo <c>redirect</c> >col quale l'utente è reindirizzato alla nuova pagina. ></p> > ><pre caption="Esempio di disclaimer"> ><?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"> >... ></pre> > ></body> ></section> ><section> ><title>FAQs</title> ><body> > ><p> >I documenti di FAQ devono incominciare con una lista di domande con i link alle >rispettive risposte. Creare una tale lista richiede molto tempo ed è soggetto ad >errori. La lista può essere creata in automatico utilizzando un elemento ><c>faqindex</c> come primo capitolo del documento. Questo elemento ha la stessa >struttura di <c>chapter</c> 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 <c>title</c> con la risposta contenuta nell'elemento <c>body</c>. >L'indice delle FAQ apparirà come una sezione per capitolo e un link per ogni >domanda. ></p> > ><p> >Uno sguardo veloce alle <uri link="/doc/it/faq.xml">FAQ</uri> e ai suoi <uri >link="/doc/it/faq.xml?passthru=1">sorgenti</uri> dovrebbe chiarire ciò che >è appena stato spiegato. ></p> > ></body> ></section> ></chapter> > ><chapter> ><title>Formato dell'Handbook</title> ><section> ><title>Guide vs Manuale</title> ><body> > ><p> >Per documentazione molto voluminosa, come <uri >link="/doc/it/handbook/handbook-x86.xml?part=1">Installazione di >Gentoo</uri>, un formato più ampio era necessario. Abbiamo sviluppato >un'estensione GuideXML-compatibile che consente di scrivere documentazione >modulare ed estesa su pagine multiple ></p> > ></body> ></section> ><section> ><title>File Principale</title> ><body> > ><p> >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: ></p> > ><pre caption="Esempio di utilizzo di un Manuale"> ><?xml version='1.0' encoding='UTF-8'?> ><!DOCTYPE book SYSTEM "/dtd/book.dtd"> ><!-- $Header$ --> > ><<i>book</i>> ><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> ></pre> > ><p> >Al momento, nessuna vera differenza (tranne il tag <c><book></c> invece di ><c><guide></c>). Invece di incominciare con i singoli ><c><chapter></c> , definire un tag <c><part></c>, che è >l'equivalente di una parte separata in un libro: ></p> > ><pre caption="Definire una parte di un libro"> ><part> ><title>Parte Uno</title> ><abstract> > ... ></abstract> > ><comment>(definire i capitoli)</comment> ></part> ></pre> > ><p> >Ogni parte è accompagnata da un tag <c><title></c> e da un tag ><c><abstract></c> che forniscono una breve introduzione alla parte. ></p> > ><p> >All'interno di ogni parte, definire i singoli<c><chapter></c>. Ogni >capitolo <e>deve</e> risiedere in un documento separato. Di conseguenza, non >deve destare stupore l'aggiunta di un tag speciale (<c><include></c>) per >consentire di includere i documenti esterni con i capitoli. ></p> > ><pre caption="Definire un capitolo"> ><chapter> ><title>Capitolo Uno</title> > ><include href="path/to/chapter-one.xml"/> > ></chapter> ></pre> > ></body> ></section> ><section> ><title>Definire i Singoli Capitoli</title> ><body> > ><p> >Il contenuto di un singolo capitolo è strutturato nel modo seguente: ></p> > ><pre caption="Sintassi di un capitolo"> ><?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> > ><comment>(Definire le <section> e le <subsection>)</comment> > ></sections> ></pre> > ><p> >All'interno di ogni capitolo è possibile definire <c><section></c> >(l'equivalente di <c><chapter></c> in una guida) e ><c><subsection></c> (l'equivalente di <c><section></c> in una guida). ></p> > ><p> >Ogni singolo capitolo dovrebbe avere i propri elementi <c><date></c> e ><c><version></c>. La data più recente di tutti i capitolo e del documento >master verrà mostrata quando un utente navigherà attraverso le parti del manuale. ></p> > ></body> ></section> ></chapter> > ><chapter> ><title>Caratteristiche Avanzate dell'Handbook</title> ><section> ><title>Variabili Globali</title> ><body> > ><p> >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. ></p> > ><p> >Variabili globali possono essere definite nel file master dell'handbook ed essere >poi utilizzate in tutti i capitoli inclusi. ></p> > ><p> >Per definire delle variabili globali, aggiungere un elemento <c><values></c> >al file master dell'handbook. Ogni variabile è definita in un elemento ><c><key></c> il cui attributo <c>id</c> definisce il nome della variabile. >Il contenuto di <c><key></c> è il valore della variabile. ></p> > ><p> >L'esempio seguente definisce tre valori in un file master di un handbook. ></p> > ><pre caption="Definire delle variabili in 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> > ><i><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></i> > ><author...> > ... ></author> > > ... ></pre> > ><p> >I valori definiti possono poi essere utilizzati attraverso l'intero handbook con >l'elemento <c><keyval id="key_id"/></c> inserito nel testo. Specificare il >nome della variabile nell'attributo <c>id</c>; ad esempio <keyval >id="min-cd-name"/> verrebbe sostituito da "install-x86-minimal-2007.0-r1.iso" >nel nostro esempio. ></p> > ><pre caption="Utilizzare i valori definiti"> ><p> >Il CD di Installazione Minimale è chiamato <c><i><keyval id="min-cd-name"/></i></c> >e richiede solo <i><keyval id="min-cd-size"/></i> 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> ></pre> > ><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 <c>min-cd-size</c> come <c>57</c> e non <c>57 MB</c>. ></p> > ></body> ></section> ><section> ><title>Elementi Condizionali</title> ><body> > ><p> >I capitoli che sono condivisi da vari handbook come <uri >link="/doc/it/handbook/">Manuale Gentoo</uri> 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: <c><section></c>, ><c><subsection></c>, <c><body></c>, <c><note></c>, ><c><impo></c>, <c><warn></c>, <c><pre></c>, <c><p></c>, ><c><table></c>, <c><tr></c>, <c><ul></c>, <c><ol></c> >and <c><li></c>. ></p> > ><p> >La condizione deve essere un'espressione <uri >link="http://it.wikipedia.org/wiki/XPath">XPATH</uri> che verrà valutata quando >verrà trasformato l'XML. Se l'espressione avrà valore <c>vero</c>, l'elemento >sarà processato, altrimenti verrà ignorato. La condizione è specificata in un >attributo <c>test</c>. ></p> > ><p> >L'esempio seguente utilizza il valore <c>arch</c> che è definito in ogni file >master dell'handbook per condizionare parte del contenuto: ></p> > ><pre caption="Utilizzare elementi condizionati"> ><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 <comment> >PPC</comment> 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> ></pre> > ></body> ></section> ></chapter> > ><chapter id="codingstyle"> > > ><title>Stile di codifica</title> ><section> ><title>Introduzione</title> ><body> > ><p> >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. ></p> > ><p> >Verranno descritte le due parti. ></p> > ></body> ></section> ><section> ><title>Stile di codifica interno</title> ><body> > ><p> >Si deve andare a capo riga (<b>interruzione di riga</b>) subito dopo <e>ogni</e> >tag Guide XML (di apertura e di chiusura), tranne che per i tag seguenti: ><c><version></c>, <c><date></c>, <c><title></c>, ><c><th></c>, <c><ti></c>, <c><li></c>, <c><i></c>, ><c><e></c>, <c><uri></c>, <c><path></c>, <c><b></c>, ><c><c></c>, <c><comment></c>, <c><mail></c> ></p> > ><p> >Le <b>righe vuote</b> devono essere inserite subito dopo <e>ogni</e> ><c><body></c> (solo tag di apertura) e prima di <e>ogni</e> ><c><chapter></c>, <c><p></c>, <c><table></c>, ><c><author></c> (set), <c><pre></c>, <c><ul></c>, ><c><ol></c>, <c><warn></c>, <c><note></c> e ><c><impo></c> (solo tag di apertura). ></p> > ><p> >Il <b>word-wrapping</b> (a capo) deve essere applicato a 80 caratteri tranne >dentro <c><pre></c>. 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 <e>renderizzato</e> all'interno di >tag <c><pre></c> dentro le 80 colonne, per aiutare gli utenti che usano la >console. ></p> > ><p> >L'<b>indentazione</b> non deve essere usata, tranne con i costrutti XML i cui >tag XML genitori sono <c><tr></c> (da <c><table></c>), ><c><ul></c>, <c><ol></c>, <c><dl></c> e <c><author></c>. >Se è usata la rientranza, essa deve essere costituita da 2 spazi. Ciò significa ><e>nessun carattere di tabulazione (<TAB>)</e> e <e>nessun ulteriore >spazio</e>. Le tabulazioni non devono essere presenti nei documenti GuideXML. ></p> > ><p> >Nel caso in cui ci sia word-wrapping in <c><ti></c>, <c><th></c>, ><c><li></c> o <c><dd></c>, è necessario indentare il contenuto</p> > ><p> >Un esempio di indentazione: ></p> > ><pre caption="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> ></pre> > ><p> ><b>Gli attributi</b> non possono avere spazi tra il segno "=" e il loro valore. >Un esempio: ></p> > ><pre caption="Specificare attributi di tag"> ><comment>Sbagliato :</comment> <pre caption = "Attributi"> ><comment>Corretto:</comment> <pre caption="Attributi"> ></pre> > ></body> ></section> ><section> ><title>Stile di codifica esterno</title> ><body> > ><p> >Nelle tabelle (<c><table></c>) e negli elenchi (<c><ul></c> e ><c><ol></c>) e <c><dl></c>, 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). ></p> > ><p> >Ogni frase, incluse quelle nelle tabelle e negli elenchi, dovrebbe iniziare con >una lettera maiuscola. ></p> > ><pre caption="Virgolette e lettere maiuscole"> ><ul> > <li>Nessun punto</li> > <li>Con punto. Frasi multiple..</li> ></ul> ></pre> > ><p> >I listati di codice dovrebbero avere <e>sempre</e> un <c>titolo</c> >(<c>caption</c>). ></p> > ><p> >Cercare di usare il più possibile <c><uri></c> con il <c>link</c>. In >altre parole, si preferisce <uri link="http://forums.gentoo.org">Forum >Gentoo</uri> rispetto a <uri>http://forums.gentoo.org</uri>. ></p> > ><p> >Quando si commenta qualcosa dentro a <c><pre></c>, usare ><c><comment></c> e delle parentesi o il segno del commento per il >linguaggio che si sta utilizzando (<c>#</c> per script bash e molte altre >cose, <c>//</c> per codice C, etc.) Mettere il commento <e>prima</e> di ciò che >si commenta. ></p> > ><pre caption="Esempio di commento"> ><comment>(Sostituire "john" con il proprio nome utente)</comment> ># <i>id john</i> ></pre> > ></body> ></section> ></chapter> > ><chapter> ><title>Risorse</title> ><section> ><title>Iniziare a scrivere</title> ><body> > ><p> >Il sistema Guide è 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 <uri >link="/proj/it/gdp/doc/doc-tipsntricks.xml">Trucchi e consigli per lo >sviluppo della documentazione</uri> potrebbe risultare molto interessante. Se si >desidera dare una mano (o si ha qualche domanda in merito a GuideXML), inviare >un messaggio alla <mail link="/main/it/lists.xml">mailing list gentoo-doc</mail> >esponendo i propri pensieri. Buon divertimento! ></p> > ></body> ></section> ></chapter> ></guide>
<b>You cannot view the attachment while viewing its details because your browser does not support IFRAMEs. <a href="attachment.cgi?id=141828">View the attachment on a separate page</a>.</b>
View Attachment As Raw
Actions:
View
Attachments on
bug 207575
: 141828
