[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