[Commits] python.it commit r221 - admin/trunk/docs
commit a svn.python.it
commit a svn.python.it
Ven 29 Set 2006 11:45:17 CEST
Author: manlio
Date: Fri Sep 29 11:45:12 2006
New Revision: 221
Added:
admin/trunk/docs/procedimento_passo_passo.ht (contents, props changed)
Log:
aggiunto documento di Antonio Vitale, con correzioni di sintassi
Added: admin/trunk/docs/procedimento_passo_passo.ht
==============================================================================
--- (empty file)
+++ admin/trunk/docs/procedimento_passo_passo.ht Fri Sep 29 11:45:12 2006
@@ -0,0 +1,276 @@
+===============================================================
+Procedimento "passo passo" per aggiornare/tradurre un documento
+===============================================================
+
+
+Introduzione
+============
+
+Questo documento illustra praticamente come procedere per l'aggiornamento
+e/o la traduzione di un documento.
+
+
+File di "update"
+================
+
+E' stato creato uno script che faciliti il compito di individuare i
+documenti da aggiornare durante il passaggio da una versione di Python
+alla successiva.
+Il risultato di questo script è un semplice file di testo accessibile
+all'indirizzo:
+http://svn.python.it/admin/branches/updates/update-python-docs-2.4.3.txt
+(in particolare questo documento riguarda il passaggio alla versione 2.4.3
+della documentazione di Python).
+Apriamolo e vediamo di capirne il contenuto!
+
+
+Spiegazione del contenuto
+-------------------------
+
+La prima parte del documento riporta un elenco di file preceduti da una
+lettera.
+
+
+::
+
+ D api/.cvsignore
+ D commontex/.cvsignore
+ D commontex/patchlevel.tex
+ D dist/.cvsignore
+ D ext/.cvsignore
+ D html/.cvsignore
+ D info/.cvsignore
+ ...
+ A html/icons/pyfav.png
+ A lib/libcookielib.tex
+ A lib/libdecimal.tex
+ A lib/libmodulefinder.tex
+ A lib/libpickletools.tex
+ A lib/libsmtpd.tex
+ A lib/libsubprocess.tex
+ A lib/libzipimport.tex
+
+
+- D equivale a "Delete" cancellare
+- A equivale a "Add" aggiungere
+
+In pratica lo script ha confrontato i nomi di file che ci sono nella nuova
+versione (da aggiornare) con quelli della vecchia.
+Poi ha proceduto a:
+
+- rimuovere quelli presenti nella vecchia ma non nella nuova versione
+ ("removing files not present in the new version");
+- aggiungere quelli presenti nella nuova ma non nella vecchia versione
+ ("copying files added in the new version").
+
+
+::
+
+ running diff... done
+ removing files not present in the new version:
+ api/.cvsignore
+ commontex/.cvsignore
+ commontex/patchlevel.tex
+ dist/.cvsignore
+ ext/.cvsignore
+ html/.cvsignore
+ info/.cvsignore
+ ...
+
+ copying files added in the new version:
+ html/icons/pyfav.png
+ unsupported document type '.png'
+ lib/libcookielib.tex
+ marking file
+ 7 markers applied
+ lib/libdecimal.tex
+ marking file
+ 13 markers applied
+ lib/libmodulefinder.tex
+ marking file
+ 1 markers applied
+ lib/libpickletools.tex
+ marking file
+ 1 markers applied
+ lib/libsmtpd.tex
+ marking file
+ 1 markers applied
+ lib/libsubprocess.tex
+ marking file
+ 4 markers applied
+ lib/libzipimport.tex
+ marking file
+ 2 markers applied
+ ...
+
+
+A questo punto lo script procede all'analisi dei singoli file
+("analyzing modified files") confrontandoli mediante "diff" con la
+precedente versione. Di seguito ad ogni file descrive il risultato.
+
+
+- "unsupported document type" significa che tale formato di file non
+ è supportato per effettuare un confronto;
+- "nothing to do" ovviamente significa che tale file non è cambiato, per
+ cui va bene così com'è;
+- "marking changed file" significa che il confronto ha avuto successo ed
+ è stata aggiunta una "marcatura" della parte modificata tra una versione
+ e l'altra.
+
+Inoltre continua elencando quante di queste marcature (che analizzeremo
+dettagliatamente in seguito) sono state aggiunte ("1 markers applied").
+Questi sono i file che bisogna tradurre/aggiornare.
+
+
+Nota::
+
+ Può succedere che di seguito a "marking changed file" segua il messaggio
+ "warning: the number of blocks does not correspond with the original (1),
+ skip". In questo caso lo script si è accorto che il file è modificato
+ tra le due versioni ma non è riuscito ad aggiungere le marcature per un
+ problema tecnico. Di questi file ci occuperemo in seguito a fine
+ aggiornamento di quelli con i marcatori, con il supporto dei coordinatori.
+
+
+Traduzione/aggiornamento pratica passo passo
+============================================
+
+Adesso che sappiamo su quali file bisogna intervenire vediamo come procedere
+praticamente.
+Il documento con i marcatori apparirà come il seguente (è stato preso come
+esempio il file "emailutil.tex" presente all'indirizzo
+http://svn.python.it/python/python/Doc/branches/2.4.3/lib/emailutil.tex
+a cui lo script ha aggiunto due marcatori).
+Apriamolo con editor di testo.
+
+
+::
+
+ \declaremodule{standard}{email.Utils}
+ %[- MARK -] BEGIN DIFF 001 of 4
+ %[- MARK -] @@ 1
+ %[- MARK -] \declaremodule{standard}{email.Utils}
+ %[- MARK -] \modulesynopsis{Miscellaneous email package utilities.}
+ %[- MARK -]
+ %[- MARK -] -There are several useful utilities provided with the \module{email}
+ %[- MARK -] -package.
+ %[- MARK -] +There are several useful utilities provided in the \module{email.Utils}
+ %[- MARK -] +module:
+ %[- MARK -]
+ %[- MARK -] \begin{funcdesc}{quote}{str}
+ %[- MARK -] Return a new string with backslashes in \var{str} replaced by two
+ %[- MARK -] backslashes, and double quotes replaced by backslash-double quote.
+ %[- MARK -] \end{funcdesc}
+ %[- MARK -] END DIFF
+ \modulesynopsis{Varie utilità del package email.}
+
+::
+
+ Ci sono varie utilità molto comode fornite con il modulo
+ \module{email}:
+
+ \begin{funcdesc}{quote}{str}
+ Restituisce una nuova stringa con i caratteri di backslashes ed i
+ doppi apici in \var{str} preceduti da una (ulteriore) backslashes.
+ \end{funcdesc}
+ ...
+
+
+Troveremo una serie di righe che iniziano con "%[- MARK -]" (sono quelle aggiunte
+dallo script). La prima di queste righe riporterà la dicitura "BEGIN DIFF 001 of 4"
+che significa che questo è il primo blocco di documento da tradurre (infatti
+lo script di seguito a questo file aveva scritto "4 markers applied").
+Poi vediamo un simbolo "@@ 1" che descrive semplicemente che il "diff" è
+partito dalla riga 1 a riportare la differenza fra le due versioni del documento.
+Importanti sono i due spazi che troviamo fra il marcatore "%[- MARK -]" e
+l'inizio della frase. Qui avremo:
+
+- un simbolo "+" che indica che questa linea è da aggiungere rispetto alla
+ precedente versione;
+- un simbolo "-" che indica che questa linea è da cancellare nella nuova versione
+ del documento.
+
+Le righe senza simbolo sono solo di contesto e servono ad aiutarci ad
+individuare dove il documento è modificato tra le due versioni.
+Il collaboratore, grazie al lavoro di confronto già svolto dallo script, basta
+che intervenga nel documento solo sulle righe con questi due simboli!
+Ovviamente non si interviene nella parte del documento con i marcatori "%[- MARK -]"
+(questa deve rimanere inalterata affinché chi revisiona il documento abbia un
+riferimento da cui partire!) ma direttamente nel testo del documento.
+In particolare nell'esempio citato dobbiamo intervenire in queste righe
+
+
+::
+
+ %[- MARK -] -There are several useful utilities provided with the \module{email}
+ %[- MARK -] -package.
+ %[- MARK -] +There are several useful utilities provided in the \module{email.Utils}
+ %[- MARK -] +module:
+
+
+Quelle con il simbolo "-" vanno rimosse e contestualmente aggiunte quelle con
+il simbolo "+".
+Quindi questa parte del documento finale tradotto sarà la seguente
+
+
+::
+
+ \declaremodule{standard}{email.Utils}
+ %[- MARK -] BEGIN DIFF 001 of 4
+ %[- MARK -] @@ 1
+ %[- MARK -] \declaremodule{standard}{email.Utils}
+ %[- MARK -] \modulesynopsis{Miscellaneous email package utilities.}
+ %[- MARK -]
+ %[- MARK -] -There are several useful utilities provided with the \module{email}
+ %[- MARK -] -package.
+ %[- MARK -] +There are several useful utilities provided in the \module{email.Utils}
+ %[- MARK -] +module:
+ %[- MARK -]
+ %[- MARK -] \begin{funcdesc}{quote}{str}
+ %[- MARK -] Return a new string with backslashes in \var{str} replaced by two
+ %[- MARK -] backslashes, and double quotes replaced by backslash-double quote.
+ %[- MARK -] \end{funcdesc}
+ %[- MARK -] END DIFF
+ \modulesynopsis{Varie utilità del package email.}
+
+::
+
+ Ci sono varie utilità molto comode fornite nel modulo
+ \module{email.Utils}:
+
+ \begin{funcdesc}{quote}{str}
+ Restituisce una nuova stringa con i caratteri di backslashes ed i
+ doppi apici in \var{str} preceduti da una (ulteriore) backslashes.
+ \end{funcdesc}
+ ...
+
+
+Adesso si può procedere ad affrontare il "DIFF 002 of 4" cioè la seconda parte
+del documento marcata e così via fino alla quarta.
+Può capitare di trovare delle righe vuote precedute dal simbolo "+" o "-" a seconda
+che siano da aggiungere o rimuovere. E' importante farlo anche se sono vuote!
+
+Una volta completato e ricontrollato il documento, lo si passa al coordinatore
+oppure in allegato alla lista docs a lists.python.it. In ogni caso è sempre bene
+comunicare in lista il nome del documento tradotto/aggiornato con il suo
+percorso completo.
+Inoltre nel caso si presenti un qualunque dubbio di traduzione si usi il glossario
+presente all'indirizzo http://svn.python.it/admin/trunk/docs/glossario.xml
+oppure si chieda tranquillamente aiuto intervenendo in lista docs a lists.python.it.
+Sicuramente altri collaboratore non vedranno l'ora di intervenire con la propria
+risposta in merito. A volte succede che il dubbio porti a più interventi e
+differenti opinioni per quanto riguarda la traduzione...ma questo è appunto
+l'aspetto più divertente del lavorare in gruppo!
+
+
+File dello stato delle traduzioni
+=================================
+
+E' stato creato un file situato all'indirizzo
+http://svn.python.it/admin/trunk/translations_status.xml che tiene conto dello
+stato di avanzamento delle traduzioni: in pratica chi ha tradotto cosa. Esso
+viene mantenuto aggiornato, con il contributo dei coordinatori, affinché rimanga
+traccia di tutti i nomi dei collaboratori che hanno partecipato all'aggiornamento
+della documentazione, oltre ai riferimenti appropriati al documento su cui sono
+intervenuti.
+
Maggiori informazioni sulla lista
Commits