Go to:
Gentoo Home
Documentation
Forums
Lists
Bugs
Planet
Store
Wiki
Get Gentoo!
Gentoo's Bugzilla – Attachment 77250 Details for
Bug 119183
[it] updated 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. 2.29 rev. 1.54 to ver. 2.29 rev. 1.57
xml-guide.xml (text/plain), 30.28 KB, created by
Gianni Costanzi
on 2006-01-16 04:15:40 UTC
(
hide
)
Description:
Updated xml-guide.xml from ver. 2.29 rev. 1.54 to ver. 2.29 rev. 1.57
Filename:
MIME Type:
Creator:
Gianni Costanzi
Created:
2006-01-16 04:15:40 UTC
Size:
30.28 KB
patch
obsolete
><?xml version = "1.0" encoding = "UTF-8"?> ><!-- $Header: /var/www/www.gentoo.org/raw_cvs/gentoo/xml/htdocs/doc/it/xml-guide.xml,v 1.21 2005/10/13 21:39:29 so Exp $ --> ><!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> > ><guide link="/doc/it/xml-guide.xml" lang="it"> ><title>Gentoo XML Guide</title> > ><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="Redazione"> ><mail link="neysx@gentoo.org">Xavier Neys</mail> ></author> ><author title="Traduttore" > ><mail link="stefano.mazzone@tin.it" >Stefano Mazzone</mail> ></author> ><author title="Traduttore" > ><mail link="so@gentoo.org">Stefano Rossi</mail> ></author> ><author title="Traduttore" > ><mail link="gianni.costanzi@gmail.com">Gianni Costanzi</mail> ></author> ><author title="Traduttore" > >Team Italiano ></author> > ><abstract> >Questa guida vi mostra come comporre documentazione web usando la nuova >sintassi Guide XML di Gentoo. Questa sintassi è il formato ufficiale della >documentazione Gentoo, e questo documento è stato creato usando Guide >XML. Questa guida presuppone una conoscenza di 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>2.29</version> ><date>2005-10-13</date> > ><chapter> ><title>Guide basics</title> ><section> ><title>Guide XML: obiettivi</title> ><body> > ><p> >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. ></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 state progettando di contribuire alla documentazione di Gentoo, o desiderate >provare Guide XML, leggete la <uri >link="/proj/it/gdp/doc/doc-tipsntricks.xml">Tips and Tricks</uri>, che contiene >consigli e trucchi per lo sviluppo della documentazione. ></p> > ><p> >Si potrebbe volere guardare il <uri link="?passthru=1">sorgente XML</uri> di >questo documento mentre state leggendo. ></p> > ></body> ></section> ></chapter> > ><chapter> ><title>Guide XML</title> ><section> ><title>Struttura di base</title> ><body> > ><p> >Si parte con l'imparare >la sintassi Guide XML. Cominceremo 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/en/guide.xml</i>" lang="<i>en</i>"> ><title><i>Gentoo Documentation Guide</i></title> > ><author title="<i>Author</i>"> > <mail link="<i>yourname@gentoo.org</i>"><i>Your Name</i></mail> ></author> > ><abstract> ><i>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.</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>29 Mar 2001</i></date> ></pre> > ><p> >Nella prima linea, troviamo il tag che identifica questo come un documento XML >e specifica il DTD. La riga <c><!-- $Header$ --></c> sarà >modificata dal server CVS e aiuta a sapere il numero delle revisioni. Di >seguito, è presente un tag <c><guide></c> -- l'intero documento è >racchiuso all'interno di una coppia di tags ><c><guide> </guide></c>. Un attributo <c>link</c> è 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 <e>devono</e> >specificare il percorso completo perchè è usato anche per controllare se >il documento originale è più recente. Un attributo <c>lang</c> dovrebbe >essere usato per specificare la lingua del codice del documento. E' usato per >formattare la data e inserire "<e>Note</e>", "<e>Content</e>", etc. nella >lingua specificata. Quella di default è inglese. ></p> > ><p> >C'è quindi un tag <c><title></c> , usato per >definire il titolo dell'intero documento. ></p> > ><p> >Arriviamo ai tags <c><author></c> , che contengono informazioni relative >ai vari autori del documento. Ogni tag <c><author></c> accetta un >elemento opzionale <c>title</c> , 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 ><c><mail></c> , usato per specificare un indirizzo email per questa >persona. Il tag <c><mail></c> è opzionale e puo essere omesso, inoltre >è richiesto non più di un elemento <c><author></c> per documento. ></p> > ><p> >Incontriamo, in seguito, i tags <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 lo stesso con il formato sbagliato. ></p> > ><p> >Questa serie di >tags dovrebbe apparire all'inizio del documento. Ad eccezione dei tags ><c><title></c> e <c><mail></c> , questi tags non dovrebbero >apparire in nessun'altra parte, eccetto immediatamente dentro il tag ><c><guide></c> , e per coerenza è raccomandato (ma non richiesto) che >questi tags appaiano prima del contenuto del documento. ></p> > ><p> >Infine abbiamo 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">Documentation Policy</uri>. ></p> > ></body> ></section> ><section> ><title>Capitoli e sezioni</title> ><body> > ><p> >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' <uri link="#doc_chap2_pre1">estratto >precedente</uri> e terminate il tutto con <c></guide></c> , avrete un >valido (anche se minimo) documento: ></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, abbiamo inserito il titolo del capitolo, >aggiungendo un elemento <c><title></c> >figlio dell'elemento <c><chapter></c> . Quindi, abbiamo creato una >sezione, aggiungendo un elemento <c><section></c> . Se guardate >all'interno dell'elemento <c><section></c> , vedrete >due elementi figli -- un <c><title></c> ed un <c><body></c>. >Mentre <c><title></c> non è nuovo, lo è <c><body></c> -- >che contiene l'attuale testo all'interno di una data sezione. Daremo >un'occhiata a quali tags sono permessi all'interno dell'elemento ><c><body></c>. ></p> > ><note> >Un elemento <c><guide></c> può contenere più elementi ><c><chapter></c>, ed un elemento <c><chapter></c> può contenere >più elementi <c><section></c>. Tuttavia, un elemento ><c><section></c> può contenere solo 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 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> ></pre> > ><p> >Ecco ora, come l'elemento <c><body></c> sotto è disegnato: ></p> > ><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="Esempio di codice"> >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> > ></body> ></section> ><section> ><title>I tags <body></title> ><body> > ><p> >Abbiamo introdotto molti nuovi tags nella sezione precedente -- ecco cosa >dovete conoscere. I tags <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 vedremo tra poco), ci sono >tags che dovrebbero apparire immediatamente all'interno dell'elemento ><c><body></c>. Un'altra cosa -- questi tags <e>non dovrebbero</e> essere >impilati -- in altre parole, non mettete un elemento <c><note></c> >all'interno di un elemento <c><p></c>. Come potete indovinare, >l'elemento <c><pre></c> preserva esattamente i suoi spazi, diventando un >ottimo elemento per pezzi di codice. Si deve nominare il tag ><c><pre></c> con un attributo <c>caption</c>: ></p> > ><pre caption="Nominare <pre>"> ><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> ></pre> > ></body> ></section> ><section> ><title>Epigrafi</title> ><body> > ><p by="Studente anonimo"> >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. ></p> > ><p> >Le epigrafi a volte sono usate all'inizio dei capitoli per mostrare 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... ></pre> > ></body> ></section> ><section> ><title><path>, <c>, <i>, <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 del tag <c><body></c>, ad eccezione di ><c><pre></c>. L'elemento <c><i></c> può essere solo usato dentro ><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 un percorso <e>assoluto che 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 <e>input >utente</e>. Pensate 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 tags 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>, aiuterete i vostri lettori a identificare >facilmente i comandi che hanno bisogno di essere digitati. Poichè gli >elementi <c><c></c> sono bilanciati da testo regolare, <e>è raramente >necessario delimitare l'input utente tra doppi apici</e>. Per esempio, non >riferitevi ad un elemento "<c><c></c>" come ho fatto in questo momento. >Evitando l'uso di doppi apici non necessari, rendiamo il documento più >leggibile -- e simpatico! ></p> > ><p> >Quando si desidera evidenziare un qualche testo come input di utente >dentro <c><pre></c>, usate invece <c><i></c>. ></p> > ><p> ><c><b></c> è usato per scrivere in <b>neretto</b> una parte di testo. ></p> > ><p> ><c><e></c> è usato per per dare enfasi ad una parola o ad una frase; per >esempio: Dovrei usare <e>realmente</e> punti e virgola molto spesso. Come >potete vedere, questo testo è bilanciato dal paragrafo per dare enfasi. >Questo vi aiuta a rafforzare le vostre 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><mail> e <uri></title> ><body> > ><p> >Abbiamo precedentemente dato un'occhiata al tag <c><mail></c>; è usato >per linkare del testo con un particolare indirizzo email, con la seguente >sintassi <c><mail link="foo@bar.com">Mr. Foo Bar</mail></c>. >Se si vuole visualizzare l'indirizzo email, si può usare ><c><mail>foo@bar.com</mail></c>, e sarà visualizzato come <mail> >foo@bar.com</mail>. ></p> > ><p> >Il tag <c><uri></c> è 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 <uri>http://forums.gentoo.org</uri>. >Per creare questo link, ho digitato ><c><uri>http://forums.gentoo.org</uri></c>. La forma alternativa è >quando volete associare un URI con qualche altro testo -- per esempio, <uri >link="http://forums.gentoo.org" >Forum Gentoo</uri>. Per creare ><e>questo</e> link, ho digitato <c><uri link="http://forums.gentoo.org"> >Forum Gentoo</uri></c>. Non si deve scrivere ><c>http://www.gentoo.org/</c> per linkare altre parti del sito web di Gentoo. >Per esempio, un link a <uri link="/doc/en/">documentation main index</uri> >dovrebbe essere <c><uri >link="/doc/en/index.xml">documentation main index</uri></c>. >Si può omettere <c>index.xml</c> quando ci si collega a una directory index, >per esempio, <c><uri >link="/doc/en/">documentation main index</uri></c>. ></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 leggenda. Non è troppo >difficile :) E' supportato anche il tag stile HTML <img src="foo.gif"/> >per aggiungere immagini senza leggenda, bordi, ecc. ></p> > ></body> ></section> ><section> ><title>Tabelle</title> ><body> > ><p> >Così come in HTML, il sistema Guide supporta una sintassi semplificata per le >tabelle. Per iniziare un tabella, usa un tag <c><table></c>. Comincia >una riga con il tag <c><tr></c> . Tuttavia, per inserire i dati nella >tabella, <e>non</e> supportiamo il tag HTML <td>; usiamo invece, ><c><th></c> per inserire una intestazione, e <c><ti></c> per >blocchi di informazioni . Potete usare <c><th></c> dovunque siano >presenti <c><ti></c> -- non è richiesto che l'elemento <c><th></c> >sia presente solo nella prima riga. ></p> > ><p> >Il tag per la tabella (<c><th></c>) accetta gli attributi ><c>colspan</c> e <c>rowspan</c> per misurare i titoli tra le righe, le >colonne o entrambi, come mostrato sotto: ></p> > ><table> > <tr> > <th colspan="4">Questo titolo misura 4 colonne</th> > </tr> > <tr> > <th rowspan="3">Questo titolo misura 3 righe</th> > <ti>Item A1</ti> > <ti>Item A2</ti> > <ti>Item A3</ti> > </tr> > <tr> > <ti>Item B1</ti> > <th colspan="2" rowspan="2">Blocky 2x2 title</th> > </tr> > <tr> > <ti>Item C1</ti> > </tr> ></table> > ></body> ></section> ><section> ><title>Liste</title> ><body> > ><p> >Per creare liste ordinate e non, usate semplicemente i tags stile XHTML ><c><ol></c>, <c><ul></c> e <c><li></c>. I tags lista >dovrebbero apparire solo all'interno dei tag <c><body></c>, ><c><li></c> ed è possibile avere liste dentro liste. Si devono chiudere >i tag anche quelli delle liste (requisito generale XML), non come HTML. ></p> > ><p> >Sono supportate le definizioni di liste (<c><dl></c>). Ne il tag di >definizione del termine, (<c><dt></c>) ne 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 contiene</dd> > <dt><c><dt></c></dt> > <dd>tag coppia di <b>D</b>efinizione del <b>T</b>ermine</dd> > <dt><c><dd></c></dt> > <dd>e tag di <b>D</b>efinizione dei <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 >che una definizione di lista contiene liste ordinate e non. Non potrebbe >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 Intra-document</title> ><body> > ><p> >E' realmente semplice fare riferimento ad altre parti di un documento usando >hyperlinks. Potete creare un link che punti ad <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>, digitate <c><uri link="#doc_chap1_sect2">Sezione 2 >del Capitolo 1</uri></c>. Per riferirsi alla Figura 3 nel Capitolo 1, >digitate <c><uri link="#doc_chap1_fig3">figure 1.3</uri></c>. O, >per riferirsi al <uri link="#doc_chap2_pre2" >Listato 2 nel Capitolo 2</uri>, >digitate <c><uri link="#doc_chap2_pre2">code listing 2.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 disclaimer predefinito all'inizio del documento. >I disclaimer disponibili sono: ></p> > ><ul> > <li> > <b>articles</b> è usato per <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 potrebbe aggiungere un >link alla nuova versione. Ci serve l'attributo <c>redirect</c>. >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 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"> >... ></pre> > ></body> ></section> ></chapter> > ><chapter> ><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 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. ></p> > ><p> >Descriviamo le due sezioni. ></p> > ></body> ></section> ><section> ><title>Stile di codifica interno</title> ><body> > ><p> ><b>Le nuove righe</b> devono essere inserite subito dopo <e>ogni</e> tag Guide >XML (di apertura e di chiusura), tranne per: ><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> ><b>Le 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> ><b>Word-wrapping</b> 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 sistemare ogni volta che c'è uno spazio. >Si dovrebbe provare a tenere gli elementi del contenuto <e>rendered</e> di ><c><pre></c> dentro le 80 colonne, per aiutare gli utenti che usano >la console. ></p> > ><p> ><b>La rientranza</b> non deve essere usata, tranne con la struttura XML della >quale i 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, ci devono essere due spazi >per ognuna. Ciò significa <e>nessuna</e> tabs e <e>nessun</e>'altri spazi. I >tab non ci devono essere 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>, la rientranza deve essere usata per il >contenuto. ></p> > ><p> >Un esempio per la rientranza: ></p> > ><pre caption="Esempio di 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> ></pre> > ><p> ><b>Gli attributi</b> non possono avere spazi tra il segno "=" e il >loro valore. Un esempio: ></p> > ><pre caption="Attributi"> ><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>, 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). ></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>Senza virgoletta</li> > <li>Con virgoletta. Frasi ripetute</li> ></ul> ></pre> > ><p> >Gli elenchi di codifica dovrebbero avere <e>sempre</e> un <c>titolo</c>. ></p> > ><p> >Cercate di usare il più possibile <c><uri></c> con il <c>link</c>. In >altre parole, è preferito <uri link="http://forums.gentoo.org"> >Forum Gentoo</uri> su <uri>http://forums.gentoo.org</uri>. ></p> > ><p> >Quando commentate qualcosa dentro a <c><pre></c>, usate ><c><comment></c> e parentesi o il segno del commento per il linguaggio >che si è usato (<c>#</c> per script bash e molte altre cose, <c>//</c> per >codice C, etc.) >Mettete il commento ><e>prima</e> del soggetto del commento. ></p> > ><pre caption="Esempio di commento"> ><comment>(Sostituite "john" con il vostro user name)</comment> ># <i>id john</i> ></pre> > ></body> ></section> ></chapter> > ><chapter> ><title>Formato del manuale</title> ><section> ><title>Guida o Manuale</title> ><body> > ><p> >Per una grande quantità di documentazione come l'<uri >link="/doc/it/handbook/handbook-x86.xml?part=1">Installazione di Gentoo</uri>, >è stato necessario ampliare il formato. Abbiamo progettato un formato >compatibile con Guide XML, che ci permettesse di scrivere la documentazione >modulare e multi-pagina. ></p> > ></body> ></section> ><section> ><title>File principale</title> ><body> > ><p> >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: ></p> > ><pre caption="Esempio di uso del Manuale"> ><?xml version='1.0' encoding='UTF-8'?> ><!DOCTYPE book SYSTEM "/dtd/book.dtd"> ><!-- $Header$ --> > ><<i>book</i> 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> ></pre> > ><p> >Finora nessuna differenza sostanziale (tranne <c><book></c> invece di ><c><guide></c>). Non si inizia con <c><chapter></c>, ma con ><c><part></c>, che è uguale all'avere una parte separata in un manuale: ></p> > ><pre caption="Definire una parte"> ><part> ><title>Prima parte</title> ><abstract> >... ></abstract> > ><comment>(Definire i molti capitoli)</comment> ></part> ></pre> > ><p> >Ogni parte è accompagnata da un <c><title></c> e un ><c><abstract></c> che serve per una breve introduzione. ></p> > ><p> >All'interno di ogni parte, si definisce ogni <c><chapter></c>. Ogni >capitolo <e>deve</e> essere un documento separato. Non è una sorpresa >l'aggiunta di un tag speciale (<c><include></c>) che permette di >includere il documento separato. ></p> > ><pre caption="Definire un capitolo"> ><chapter> ><title>Primo capitolo</title> ><abstract> > Questa è una piccola spiegazione sul primo capitolo. ></abstract> > > <include href="path/to/chapter-one.xml"/> > ></chapter> ></pre> > ></body> ></section> ><section> ><title>Progettazione dei capitoli</title> ><body> > ><p> >Il contenuto di un capitolo è strutturato come segue: ></p> > ><pre caption="Sintassi del 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> > ><version>...</version> ><date>...</date> > ><comment>(Definire le molte <section> e <subsection>)</comment> > ></sections> ></pre> > ><p> >In ogni capitolo si possono definire <c><section></c> (equivalente di ><c><chapter></c> in una Guida), e <c><subsection></c> (equivalente >di <c><section></c> in una Guida). ></p> > ><p> >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. ></p> > ></body> ></section> ></chapter> > ><chapter> ><title>Risorse</title> ><section> ><title>Iniziare a scrivere</title> ><body> > ><p> >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 ><uri link="/proj/it/gdp/doc/doc-tipsntricks.xml">Documentation >Development Tips & Tricks</uri>. >Se vi piacerebbe aiutarci (o avete >qualche domanda in merito), inviate un messaggio <mail >link="gentoo-doc@gentoo.org" >alla gentoo-doc mailing list</mail> dichiarando >cosa vi piacerebbe fare. 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=77250">View the attachment on a separate page</a>.</b>
View Attachment As Raw
Actions:
View
Attachments on
bug 119183
: 77250
