Attachment 83155 Details for Bug 127635 – Updated doc-tipsntricks.xml from ver. 0.17 rev. 1.12 to ver. 0.19 rev. 1.14

Updated doc-tipsntricks.xml from ver. 0.17 rev. 1.12 to ver. 0.19 rev. 1.14

doc-tipsntricks.xml (text/plain), 18.72 KB, created by Gianni Costanzi on 2006-03-26 05:12:44 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Gianni Costanzi

Created: 2006-03-26 05:12:44 UTC

Size: 18.72 KB

patch

obsolete

><?xml version='1.0' encoding="UTF-8"?>
><!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
>
><guide link="/proj/it/gdp/doc/doc-tipsntricks.xml" lang="it">
><title>Trucchi e consigli per lo sviluppo della documentazione</title>
>
><author title="Autore">
> <mail link="swift@gentoo.org">Sven Vermeulen</mail>
></author>
><author title="Redattore">
> <mail link="neysx@gentoo.org">Xavier Neys</mail>
></author>
><author title="Traduttore">
> <mail link="matteo.visconti@solka.it">Matteo Visconti</mail>
></author>
><author title="Traduttore">
> <mail link="gianni.costanzi@gmail">Gianni Costanzi</mail>
></author>
>
><abstract>
>Alcuni trucchi e consigli che possono rendere piÃ¹ semplice la vita di un
>redattore di documenti per Gentoo.
></abstract>
>
><license/>
>
><version>0.19</version>
><date>2006-03-21</date>
>
><chapter>
><title>Impostare l'ambiente locale</title>
><section>
><title>Ambiente locale per i collaboratori</title>
><body>
>
>
>Si crei una directory dedicata allo sviluppo della documentazione. Si prenda
>ad esempio <path>~/work/gentoo/doc</path>. All'interno di questa directory,
>si crei una sotto-directory (per esempio, <path>en/</path>) nella quale si
>terrÃ  la documentazione inglese aggiornata.
>
>
>
>Si scarichi il pacchetto con la documentazione inglese piÃ¹ recente:
>
>
><pre caption="Scaricare la documentazione inglese">
>$ wget http://www.gentoo.org/dyn/doc-snapshots/docs-latest-en.tar.bz2
></pre>
>
>
>Si decomprima la documentazione nella directory <path>en/</path>. Ora si
>possiede un'immagine aggiornata della documentazione inglese. Ogni volta che si
>desidera aggiornare questa immagine, si puÃ² scaricare nuovamente il pacchetto,
>ma Ã¨ anche possibile caricare la pagina del documento e aggiungere
><path>?passthru=1</path> all'URL. Per esempio:
>
>
><pre caption="Aggiornare un documento inglese">
>$ wget http://www.gentoo.org/doc/en/alsa-guide.xml?passthru=1 -O alsa-guide.xml
></pre>
>
>
>Nel caso si voglia aiutare nella traduzione dei documenti, si consiglia di
>creare una directory per la propria lingua, nella quale si terranno le
>traduzioni correnti:
>
>
><pre caption="Scaricare la documentazione per la propria lingua">
>$ mkdir <comment>${LANG}</comment>
>$ cd <comment>${LANG}</comment>
>$ wget http://www.gentoo.org/dyn/doc-snapshots/docs-latest-<comment>${LANG}</comment>.tar.bz2
>$ tar xvjf docs-latest-*.tar.bz2
></pre>
>
>
>Quando si aggiorna un documento, Ã¨ necessario copiarlo dalla directory
><path>${LANG}/</path> a quella principale (<path>~/work/gentoo/doc</path>) e
>modificare la versione copiata. E' necessario avere l'originale per creare una
>patch:
>
>
>
><pre caption="Creare una patch per un aggiornamento">
>$ diff -U6 <comment>${LANG}</comment>/alsa-guide.xml alsa-guide.xml > alsa-guide.diff
></pre>
>
></body>
></section>
><section>
><title>Deposito CVS online</title>
><body>
>
>
>Si puÃ² richiedere il <uri link="/cgi-bin/viewcvs.cgi">deposito CVS online</uri>
>per ottenere le differenze tra singole versioni. Si puÃ² accedere al deposito
>inglese principale da <uri
> link="/cgi-bin/viewcvs.cgi/en/?root=doc&amp;sortby=date">questo link</uri>
>(ndT: quello italiano Ã¨ reperibile a <uri
> link="/cgi-bin/viewcvs.cgi/it/?root=doc&amp;sortby=date">questo link</uri>).
>Il deposito CVS online Ã¨ aggiornato ogni ora.
>
>
></body>
></section>
><section>
><title>Deposito locale per gli sviluppatori</title>
><body>
>
>
>Si crei una directory dedicata a Gentoo; per esempio
><path>~/work/gentoo/doc</path>. Poi si crei una sotto-directory chiamata
><path>cvs/</path> nella quale si metterÃ  l'immagine del CVS.
>
>
><pre caption="Ottenere l'immagine del CVS">
>$ mkdir cvs; cd cvs/
>$ export CVSROOT=<comment>&lt;il proprio nick&gt;</comment>@cvs.gentoo.org:/var/cvsroot
>$ cvs co doc
></pre>
>
>
>Per aggiornare l'immagine CVS, si esegua il comando <c>cvs update -dP</c> nella
>directory <path>cvs/doc</path>.
>
>
></body>
></section>
></chapter>
><chapter>
><title>Provare GuideXML</title>
><section>
><title>Provare l'ambiente</title>
><body>
>
>
>Per primo si crei una directory <path>test/</path> nella quale vengono copiati
><path>guide.dtd</path>, <path>main.css</path> e alcune immagini:
>
>
><pre caption="Creare l'ambiente di prova">
>$ mkdir test
>$ cd test
>$ mkdir css images
>$ wget -P css/ http://www.gentoo.org/css/main.css
>$ wget -P images/ http://www.gentoo.org/images/gridtest.gif \
> http://www.gentoo.org/images/gtop-new.gif \
> http://www.gentoo.org/images/gtop-www.jpg
></pre>
>
>
>Ora si scarichi una versione speciale di <path>guide.xsl</path> ottenibile dal
><uri link="http://dev.gentoo.org/~neysx/guide.xsl">pagina di
> neysx</uri>. Questa versione Ã¨ modificata per trasformare GuideXML in HTML su
>sistemi locali e supporta alcuni linguaggi. E' anche disponibile una <uri
> link="http://dev.gentoo.org/~neysx/guide-en.xsl">versione molto piÃ¹
> piccola</uri> che supporta solo l'inglese.
>
>
><pre caption="Scaricare guide.xsl">
>$ wget http://dev.gentoo.org/~neysx/guide.xsl
><comment>(Oppure, se vi serve solo il supporto per l'inglese)</comment>
>$ wget -O guide.xsl http://dev.gentoo.org/~neysx/guide-en.xsl
></pre>
>
>
>Infine, si modifichi <path>/etc/xml/catalog</path> come root aggiungendo le
>linee seguenti:
>
>
><pre caption="Aggiunta di /etc/xml/catalog">
>&lt;rewriteURI uriStartString="/dtd" rewritePrefix="/usr/portage/metadata/dtd/"/&gt;
></pre>
>
>
>Se il proprio <path>/etc/xml/catalog</path> Ã¨ vuoto o non contiene nessun
>elemento, Ã¨ necessario <e>inserire</e> l'elemento <c>&lt;rewriteURI&gt;</c>
><e>all'interno</e> dell'elemento <c>&lt;catalog&gt;</c>:
>
>
><pre caption="/etc/xml/catalog minimale">
>&lt;?xml version="1.0"?&gt;
>&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
>&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"&gt;
>&lt;rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/&gt;
>&lt;/catalog&gt;
></pre>
>
>
>Inoltre, alcuni file potrebbero specificare il DTD on-line con un'uri come
><path>http://www.gentoo.org/dtd/guide.dtd</path>. E' possibile rinominare questi
>riferimenti ed evitare cosÃ¬ accessi lenti alla rete:
>
>
><pre caption="Extra /etc/xml/catalog addendum">
>&lt;rewriteURI uriStartString="http://www.gentoo.org/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/&gt;
></pre>	
>
></body>
></section>
><section>
><title>Provare una guida di Gentoo</title>
><body>
>
>
>Per provare una guida di Gentoo, per prima cosa si controlli se utilizza una
>sintassi XML corretta:
>
>
><pre caption="Usare xmllint per verificare le guide">
>$ xmllint --valid --noout alsa-guide.xml
></pre>
>
>
>Se <c>xmllint</c> termina senza indicare nulla, la sintassi XML del file Ã¨
>corretta. Quindi Ã¨ necessario convertirlo in HTML. <c>xsltproc</c> Ã¨ il
>programma utilizzato per fare ciÃ²:
>
>
><pre caption="Convertire in HTML">
>$ xsltproc --novalid test/guide.xsl alsa-guide.xml &gt; test/alsa-guide.html
></pre>
>
>
>Se non Ã¨ indicato nessun errore, si dovrebbe essere in grado di aprire il file
>con il proprio browser (digitando
><uri>file:///home/user/work/gentoo/doc/test/alsa-guide.html</uri> nella barra
>degli indirizzi, dove <e>user</e> Ã¨ il nome del proprio utente) per
>visualizzare il documento. Se non Ã¨ possibile farlo, si corregga la propria
>guida finchÃ¨ non funziona.
>
>
></body>
></section>
><section>
><title>Provare il Manuale di Gentoo</title>
><body>
>
>
>Il Manuale di Gentoo Ã¨ diviso in capitoli. Per trasformare in HTML come se fosse
>sul nostro web server un
>determinato capitolo, Ã¨ necessario usare sia il file
><path>handbook-x86.xml</path> sia il file <path>hb-</path> desiderato (per
>esempio, <path>hb-install-about.xml</path>). Quindi bisogna eseguire
><c>xsltproc</c> dando gli stessi parametri utilizzati mentre si sfoglia online
>il manuale, indicando <c>part</c> e <c>chap</c>. Segue un esempio di come
>verificare la validitÃ  di <path>hb-install-about.xml</path>. Si prega di notare
>che sono necessari anche tutti i file che l'handbook include.
>
>
>
>In alternativa, Ã¨ anche possibile processare un capitolo dell'handbook come
>qualsiasi altra guida, ma i link verso gli altri capitoli non saranno generati.
>
>
><pre caption="Verificare la validitÃ  di hb-install-about.xml">
>$ xmllint --valid --noout handbook-x86.xml
>$ xmllint --valid --noout hb-install-about.xml
>$ xsltproc --stringparam part 1 --stringparam chap 1 test/guide.xsl handbook-x86.xml &gt; test/hb-install-about.html
>
><comment>(oppure la via piÃ¹ semplice)</comment>
>
>$ xsltproc test/guide.xsl hb-install-about.xml &gt; test/hb-install-about.html
></pre>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Usare un'installazione di axkit</title>
><section>
><body>
>
><note>
>Questo capitolo non Ã¨ attualmente aggiornato ed Ã¨ ancora presente solo per
>motivi storici poichÃ¨ uno dei nostri web server utilizza ancora un'installazione
>axkit. Qualcuno potrebbe volerlo provare.
></note>
>
>
>Alcuni sviluppatori di documenti preferiscono utilizzare un'installazione di
>axkit simile a quella che Ã¨ usata su <uri>http://www.gentoo.org</uri>. Di
>seguito alcune dritte per installare una configurazione simile.
>
>
><warn>
>Sembra che axkit sia molto sensibile alle versioni dei pacchetti che utilizza,
>specialmente a quelle di libxml2. La configurazione descritta di seguito Ã¨
>correttamente funzionante. Altre combinazioni di pacchetti potrebbero non
>funzionare.
></warn>
>
>
>Per prima cosa si installino i pacchetti richiesti:
>
>
><pre caption="Installare la versioni specifiche dei pacchetti richiesti">
><comment>(Controllare se i pacchetti sono disponibili in portage)</comment>
># emerge -vp =dev-libs/libxml2-2.6.17 =dev-libs/libxslt-1.1.12 \
>=dev-perl/AxKit-1.6.1 =dev-perl/XML-XPath-1.13 =dev-perl/XML-LibXML-1.58 \
>=dev-perl/XML-LibXSLT-1.57 =dev-perl/XML-Parser-2.34 =net-www/apache-1.3.33
>
>These are the packages that I would merge, in order:
>
>Calculating dependencies ...done!
>[ebuild R ] dev-libs/libxml2-2.x.17 -debug -ipv6 +python +readline 0 kB
>[ebuild R ] dev-libs/libxslt-1.1.12 +crypt +python 0 kB
>[ebuild R ] dev-perl/AxKit-1.6.1 +gnome 0 kB
>[ebuild R ] dev-perl/XML-XPath-1.13 0 kB
>[ebuild R ] dev-perl/XML-LibXML-1.58 0 kB
>[ebuild R ] dev-perl/XML-LibXSLT-1.57 0 kB
>[ebuild R ] dev-perl/XML-Parser-2.34 0 kB
>[ebuild R ] net-www/apache-1.3.33 +pam 0 kB
>
><comment>(Installare i pacchetti)</comment>
># emerge =dev-libs/libxml2-2.6.17 =dev-libs/libxslt-1.1.12 \
>=dev-perl/AxKit-1.6.1 =dev-perl/XML-XPath-1.13 =dev-perl/XML-LibXML-1.58 \
>=dev-perl/XML-LibXSLT-1.57 =dev-perl/XML-Parser-2.34 =net-www/apache-1.3.33
></pre>
>
>
>Quindi si modifichino i seguenti file di configurazione:
>
>
><pre caption="/etc/apache/conf/commonapache.conf">
><comment>(All'interno)</comment>
>&lt;IfModule mod_dir.c&gt;
> <comment>(Aggiungere index.xml alla lista)</comment>
> <comment>(ndT: se apache dovesse dare un errore riguardo al file commonapache.conf, 
> si consiglia di porre gli argomenti di DirectoryIndex in un'unica riga)</comment>
> DirectoryIndex index.xml index.html index.php index.php3 \
> index.shtml index.cgi index.pl index.htm Default.htm default.htm
>&lt;/IfModule&gt;
>
><comment>(Aggiungere le linee seguenti)</comment>
>&lt;IfDefine PERL&gt;
> LoadModule perl_module extramodules/libperl.so
># AddModule mod_perl.c
> PerlModule AxKit
> SetHandler perl-script
> PerlHandler Apache::AxKit::StyleChooser::PathInfo AxKit
> AddHandler axkit .xml .xsp
> AxAddPlugin Apache::AxKit::StyleChooser::QueryString
> AxAddXSPTaglib AxKit::XSP::Util
> AxAddXSPTaglib AxKit::XSP::IfParam
> AxAddXSPTaglib AxKit::XSP::Param
> AxAddStyleMap application/x-xsp Apache::AxKit::Language::XSP
> AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT
> &lt;AxStyleName "#default"&gt;
> AxAddProcessor text/xsl /xsl/guide.xsl
> &lt;/AxStyleName&gt;
> &lt;AxStyleName printable&gt;
> AxAddProcessor text/xsl /xsl/guide-print.xsl
> &lt;/AxStyleName&gt;
>&lt;/IfDefine&gt;
>
><comment>(All'interno)</comment>
>&lt;IfModule mod_alias.c&gt;
> Alias /icons/ /var/www/localhost/icons/
><comment>(Commentare la linea seguente)</comment>
> #Alias /doc /usr/share/doc
></pre>
>
><pre caption="/etc/conf.d/apache">
><comment>(Aggiungere -D PERL alla lista delle opzioni)</comment>
>APACHE_OPTS="-D PERL"
></pre>
>
>
>Quindi si copino i file di documentazione, includendo i file DTD e i fogli di
>stile, in <path>/var/www/localhost/htdocs/</path>. E' necessario avere le
>directory <path>css/</path>, <path>doc/</path>, <path>dtd/</path>,
><path>images/</path> e <path>xsl/</path>. Gli sviluppatori gentoo possono
>copiarli o creare un symlink alla loro copia CVS locale. Gli altri
>collaboratori devono scaricare i file dalla nostra interfaccia <uri
>link="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/?root=gentoo">viewCVS</uri>.
>
>
>
>Rimane solo da far partire il server apache:
>
>
><pre caption="Eseguire apache">
># /etc/init.d/apache start
># <comment>(Aggiungerlo al runlevel di default se si vuole che venga eseguito automaticamente all'avvio)</comment>
># rc-update add apache default
></pre>
>
>
>Ora Ã¨ possibile collegarsi al sito <uri>http://tuo_server/doc/en/</uri> o
>semplicemente <uri>http://localhost/doc/en/</uri> se axkit Ã¨ stato installato
>sul proprio computer. Si puÃ² controllare il file
><path>/var/log/apache/access_log</path> per gli accessi e
><path>/var/log/apache/error_log</path> per gli errori.
>
>
><note>
>Gli utenti dei browser Mozilla, che utilizzano axkit su localhost, potrebbero
>aver bisogno di impostare nella loro pagina <uri>about:config</uri> l'opzione
><c>keyword.enabled</c> in <c>false</c>.
></note>
>
></body>
></section>
>
></chapter>
>
><chapter>
><title>Domande frequenti</title>
><section>
><title>Come posso convertire un file in UTF-8?</title>
><body>
>
>Ci sono alcuni programmi che posso aiutare. Uno molto conosciuto Ã¨
><c>app-test/recode</c>. Un altro Ã¨ <c>iconv</c>, contenuto nel pacchetto
><c>sys-libs/glibc</c>.
>
>
>
>Recode Ã¨ molto semplice da usare. Si indica la codifica dei caratteri usata dal
>file e quella che invece si vuole utilizzare nel documento convertito.
>
>
>
>Per esempio per convertire un documento dalla codifica ISO-8859-15 (conosciuta
>anche come Latin-9) alla codifica UTF-8, si procede nel modo seguente:
>
>
><pre caption="Convertire un file">
><comment>(l9 = ISO-8859-15, u8 = UTF-8)</comment>
>$ recode l9..u8 file.xml
></pre>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Suggerimenti sulla Sottomissione di Documentazione</title>
><section>
><title>Controllare la correttezza dei tag &lt;guide&gt;</title>
><body>
>
>
>Ci si assicuri che l'attributo &lt;guide link&gt; punti alla corretta locazione
>per la guida. Questa Ã¨ generalmente <path>/doc/${LANG}/filename.xml</path>. Se
>si ha un documento tradotto, si specifichi sempre il percorso assoluto del
>documento (ad esempio <path>/doc/${LANG}/</path>). Se si sta scrivendo una guida
>che utilizza i DTD <c>guide</c> o <c>book</c>, Ã¨ possibile utilizzare sia
><path>/doc/${LANG}/filename.xml</path> che <path>filename.xml</path>. In
>generale, il GDP raccomanda la prima delle due modalitÃ .
>
>
></body>
></section>
><section>
><title>Controllare i link</title>
><body>
>
>
>E' <e>necessario</e> controllare che tutti i link ipertestuali nel proprio
>documento siano corretti. Se si tratta di un documento tradotto, ci si assicuri
>che i link ad altri documenti tradotti puntino a file esistenti.
>
>
></body>
></section>
><section>
><title>Controllate le tabulazioni</title>
><body>
>
>
>Le tabulazioni sono assolutamente proibite nei documenti GuideXML tranne quando
>necessarie (ad esempio se il documento istruisce gli utenti a come utilizzare le
>tabulazioni). Per controllare le tabulazioni in un documento, eseguire <c>grep
>"CTRL+V&lt;TAB&gt;" file.xml</c>. Si sistemino tutte le linee stampate da
><c>grep</c>
>
>
></body>
></section>
><section>
><title>Bugzilla</title>
><body>
>
>
>Una volta ultimato il documento, lo si sottometta al Documentation Team
>utilizzando <uri
> link="http://bugs.gentoo.org/enter_bug.cgi?product=Documentation">Bugzilla</uri>.
>Non Ã¨ necessario riportare informazioni come la piattaforma, l'output di
><c>emerge info</c>, arch, passi necessari per riprodurre il problema, ecc. Se
>si possiede un documento tradotto, ci si assicuri di scegliere il campo <uri
>link="http://bugs.gentoo.org/enter_bug.cgi?product=Doc%20Translations">Doc
>Translations</uri> per il vostro bug. Inoltre, si includa un utile sommario per
>la vostra traduzione utilizzando il formato favorito: "[fr] New translation:
>/doc/fr/gnupg-user.xml". Si sostituisca [fr] con il codice a due lettere
>del vostro linguaggio.
>
>
>
>Di default, <mail>docs-team@gentoo.org</mail> Ã¨ il destinatario (assignee) del
>vostro bug: non c'Ã¨ alcun bisogno di modificare il campo assignee.
>
>
>
>Si alleghino file e patch al bug utilizzando la modalitÃ  "plain text
>(text/plain)", anche se si sta sottomettendo un file <path>.xml</path> Le patch
>dovrebbero avere l'opzione "Patch" marcata. Non si sottomettano tarballs piene
>di documenti; si alleghi ogni documento e patch individualmente.
>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Errori comuni o pericolosi</title>
><section>
><title>Dimenticare che il Manuale Gentoo riguarda tutte le architetture</title>
><body>
>
>
>I file presenti in <path>[gentoo]/xml/htdocs/doc/it/handbook</path> che non
>terminano con il suffisso &quot;-&lt;arch&gt;.xml&quot; sono usati in
><e>tutti</e> i manuali, quindi qualunque file di questo tipo deve essere
>universale per ogni architettura.
>
>
>
>Se si ha bisogno di apportare delle modifiche per la propria architettura e si
>teme di dover creare un nuovo file per questo, prima di compiere qualunque
>modifica bisogna chiedere aiuto a <c>gentoo-doc@gentoo.org</c>. Molte volte c'Ã¨
>una soluzione piÃ¹ semplice che evita di creare problemi agli utenti di altre
>architetture.
>
>
>
></body>
></section>
><section>
><title>Non modificare la versione e la data</title>
><body>
>
>
>Come esige il regolamento per lo sviluppo della documentazione, si <e>deve</e>
>cambiare la versione e la data quando si compiono delle modifiche. Sebbene la
>versione sia meno importante, la data serve agli utenti per sapere quando Ã¨
>avvenuta l'ultima modifica.
>
>
>
>Se si sta apportando un cambiamento di <e>contenuto</e> al documento (come
>istruzioni, esempi di codice, ecc), si deve incrementare la versione. Per
>cambiamenti <e>non di contenuto</e> (ad esempio errori di scrittura o correzioni
>nell GuideXML), il salto di versione non Ã¨ di solito necessario.
>
>
>
>Quando si aggiorna il manuale, si deve modificare la data e la versione dei soli
>file modificati. Non modificare il file handbook-<e>ARCH</e>.xml a meno che non
>si abbia modificato effettivamente quel file.
>
>
>
>Un altro errore comune Ã¨ aggiornare il numero della versione come se fosse un
>numero decimale. <c>3.9</c> diventa <c>3.10</c>, non <c>4.0</c> o <c>3.91</c>.
>
>
></body>
></section>
></chapter>
>
></guide>

Actions: View

Attachments on bug 127635: 83155