[Commits] python.it commit r230 - admin/trunk/docs
commit a svn.python.it
commit a svn.python.it
Lun 23 Ott 2006 17:39:20 CEST
Author: manlio
Date: Mon Oct 23 17:39:16 2006
New Revision: 230
Modified:
admin/trunk/docs/procedimento_passo_passo.ht
Log:
modifica e aggiornamento di ANtonio Vitale
Modified: admin/trunk/docs/procedimento_passo_passo.ht
==============================================================================
--- admin/trunk/docs/procedimento_passo_passo.ht (original)
+++ admin/trunk/docs/procedimento_passo_passo.ht Mon Oct 23 17:39:16 2006
@@ -4,18 +4,19 @@
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
@@ -25,7 +26,7 @@
Spiegazione del contenuto
--------------------------
+'''''''''''''''''''''''''
La prima parte del documento riporta un elenco di file preceduti da una
lettera.
@@ -51,17 +52,17 @@
A lib/libzipimport.tex
-- D equivale a "Delete" cancellare
-- A equivale a "Add" aggiungere
+- **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:
+ 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");
+ (*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").
+ (*copying files added in the new version*).
::
@@ -105,42 +106,47 @@
A questo punto lo script procede all'analisi dei singoli file
-("analyzing modified files") confrontandoli mediante "diff" con la
+(*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
+- **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
+- **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
+- **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.
+dettagliatamente in seguito) sono state aggiunte (*1 markers applied*).
+Questi sono i file che bisogna tradurre/aggiornare oltre ai nuovi inseriti (vedi
+apposita sezione)
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.
+ 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 tra le due versioni il file è
+ stato modificato 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
+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.
@@ -176,27 +182,35 @@
...
-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"
+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" è
+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:
+Importanti sono i due spazi che troviamo fra il marcatore **%[- MARK -]** e
+l'inizio della frase.
-- un simbolo "+" che indica che questa linea è da aggiungere rispetto alla
+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
+- 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 -]"
+
+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
@@ -208,9 +222,10 @@
%[- 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
+Quelle con il simbolo **-** vanno rimosse e contestualmente aggiunte quelle con
+il simbolo **+**.
+
+Quindi questa parte del documento finale tradotto sarà la seguente:
::
@@ -245,18 +260,108 @@
...
-Adesso si può procedere ad affrontare il "DIFF 002 of 4" cioè la seconda parte
+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!
+
+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!**
+
+
+File nuovi non presenti nella precedente versione
+'''''''''''''''''''''''''''''''''''''''''''''''''
+
+Per quanto riguarda la traduzione dei file nuovi che non erano presenti nella
+vecchia versione (quelli **added**) il procedimento è molto simile.
+
+In particolare essi saranno suddivisi in pezzi da 100 righe per facilitare la
+suddivisione del lavoro fra i vari traduttori.
+
+All'inizio di ogni pezzetto da 100 righe ci sarà presente un marcatore del tipo
+**%[- MARK -] BEGIN PART 001 of 21** che aiuta il collaboratore ad individuare
+quale pezzetto tradurre.
+
+Ovviamente tale marcatore non deve essere rimosso!
+
+Si procede quindi con la traduzione di un paragrafo alla volta lasciando il
+testo originale in inglese per facilitare al coordinatore la revisione del documento.
+
+Ecco a titolo di esempio come si presenta un documento prima della traduzione:
+
+
+::
+
+ %[- MARK -] BEGIN PART 001 of 21
+ Optional \var{localtime} is a flag that when \code{True}, interprets
+ \var{timeval}, and returns a date relative to the local timezone
+ instead of UTC, properly taking daylight savings time into account.
+ The default is \code{False} meaning UTC is used.
+
+ Optional \var{usegmt} is a flag that when \code{True}, outputs a
+ date string with the timezone as an ascii string \code{GMT}, rather
+ than a numeric \code{-0000}. This is needed for some protocols (such
+ as HTTP). This only applies when \var{localtime} is \code{False}.
+ \versionadded{2.4}
+ \end{funcdesc}
+
+ \begin{funcdesc}{make_msgid}{\optional{idstring}}
+ Returns a string suitable for an \rfc{2822}-compliant
+ \mailheader{Message-ID} header.
+ ...
+
+e come diventa dopo:
+
+
+::
+
+ %[- MARK -] BEGIN PART 001 of 21
+ Optional \var{localtime} is a flag that when \code{True}, interprets
+ \var{timeval}, and returns a date relative to the local timezone
+ instead of UTC, properly taking daylight savings time into account.
+ The default is \code{False} meaning UTC is used.
+
+ Il parametro facoltativo \var{localtime} è un'opzione che, quando
+ \code{True}, interpreta \var{timeval} e restituisce una data relativa
+ al tempo locale invece di UTC, tenendo in debita considerazione l'ora
+ legale. Il valore predefinito è \code{False}, a significare che viene
+ utilizzato UTC.
+
+ Optional \var{usegmt} is a flag that when \code{True}, outputs a
+ date string with the timezone as an ascii string \code{GMT}, rather
+ than a numeric \code{-0000}. This is needed for some protocols (such
+ as HTTP). This only applies when \var{localtime} is \code{False}.
+ \versionadded{2.4}
+ \end{funcdesc}
+
+ Il parametro facoltativo \var{usegmt} è un'opzione che, quando \code{True},
+ produce una stringa contenente la data con il fuso orario espresso come una
+ stringa ascii \code{GMT}, piuttosto che come numero \code{-0000}.
+ Questo è richiesto per diversi protocolli (come l'HTTP). Tutto ciò si usa
+ solo quando \var{localtime} corrisponde a \code{False}.\versionadded{2.4}
+ \end{funcdesc}
+
+ \begin{funcdesc}{make_msgid}{\optional{idstring}}
+ Returns a string suitable for an \rfc{2822}-compliant
+ \mailheader{Message-ID} header.
+
+ \begin{funcdesc}{make_msgid}{\optional{idstring}}
+ Restituisce una stringa utilizzabile per un'intestazione
+ \mailheader{Message-ID} compatibile con la \rfc{2822}.
+ ...
+
+Note finali
+-----------
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
+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
@@ -264,13 +369,14 @@
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.
+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