<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Procedimento "passo passo" per aggiornare/tradurre un documento</title>
<link rel="stylesheet" href="../docutils/writers/html4css1/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="procedimento-passo-passo-per-aggiornare-tradurre-un-documento">
<h1 class="title">Procedimento "passo passo" per aggiornare/tradurre un documento</h1>
<div class="section" id="introduzione">
<h1><a name="introduzione">Introduzione</a></h1>
<p>Questo documento illustra praticamente come procedere per l'aggiornamento
e/o la traduzione di un documento.</p>
</div>
<div class="section" id="file-di-update">
<h1><a name="file-di-update">File di "update"</a></h1>
<p>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.</p>
<p>Il risultato di questo script è un semplice file di testo accessibile
all'indirizzo:
<a class="reference" href="http://svn.python.it/admin/branches/updates/update-python-docs-2.4.3.txt">http://svn.python.it/admin/branches/updates/update-python-docs-2.4.3.txt</a>
(in particolare questo documento riguarda il passaggio alla versione 2.4.3
della documentazione di Python).
Apriamolo e vediamo di capirne il contenuto!</p>
<div class="section" id="spiegazione-del-contenuto">
<h2><a name="spiegazione-del-contenuto">Spiegazione del contenuto</a></h2>
<p>La prima parte del documento riporta un elenco di file preceduti da una
lettera.</p>
<pre class="literal-block">
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
</pre>
<ul>
<li><p class="first"><strong>D</strong> equivale a <strong>Delete</strong> cancellare</p>
</li>
<li><p class="first"><strong>A</strong> equivale a <strong>Add</strong> aggiungere</p>
<blockquote>
<p>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:</p>
</blockquote>
</li>
<li><p class="first">rimuovere quelli presenti nella vecchia ma non nella nuova versione
(<em>removing files not present in the new version</em>);</p>
</li>
<li><p class="first">aggiungere quelli presenti nella nuova ma non nella vecchia versione
(<em>copying files added in the new version</em>).</p>
</li>
</ul>
<pre class="literal-block">
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
...
</pre>
<p>A questo punto lo script procede all'analisi dei singoli file
(<em>analyzing modified files</em>) confrontandoli mediante <strong>diff</strong> con la
precedente versione. Di seguito ad ogni file descrive il risultato.</p>
<ul class="simple">
<li><strong>unsupported document type</strong> significa che tale formato di file non
è supportato per effettuare un confronto;</li>
<li><strong>nothing to do</strong> ovviamente significa che tale file non è cambiato, per
cui va bene così com'è;</li>
<li><strong>marking changed file</strong> significa che il confronto ha avuto successo ed
è stata aggiunta una <em>marcatura</em> della parte modificata tra una versione
e l'altra.</li>
</ul>
<p>Inoltre continua elencando quante di queste marcature (che analizzeremo
dettagliatamente in seguito) sono state aggiunte (<em>1 markers applied</em>).
Questi sono i file che bisogna tradurre/aggiornare oltre ai nuovi inseriti (vedi
apposita sezione)</p>
<p>Nota:</p>
<pre class="literal-block">
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.
</pre>
</div>
</div>
<div class="section" id="traduzione-aggiornamento-pratica-passo-passo">
<h1><a name="traduzione-aggiornamento-pratica-passo-passo">Traduzione/aggiornamento pratica passo passo</a></h1>
<p>Adesso che sappiamo su quali file bisogna intervenire vediamo come procedere
praticamente.</p>
<p>Il documento con i marcatori apparirà come il seguente (è stato preso come
esempio il file <em>emailutil.tex</em> presente all'indirizzo
<a class="reference" href="http://svn.python.it/python/python/Doc/branches/2.4.3/lib/emailutil.tex">http://svn.python.it/python/python/Doc/branches/2.4.3/lib/emailutil.tex</a>
a cui lo script ha aggiunto due marcatori).</p>
<p>Apriamolo con editor di testo.</p>
<pre class="literal-block">
\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.}
</pre>
<pre class="literal-block">
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}
...
</pre>
<p>Troveremo una serie di righe che iniziano con <strong>%[- MARK -]</strong> (sono quelle aggiunte
dallo script).</p>
<p>La prima di queste righe riporterà la dicitura <strong>BEGIN DIFF 001 of 4</strong>
che significa che questo è il primo blocco di documento da tradurre (infatti
lo script di seguito a questo file aveva scritto <em>4 markers applied</em>).</p>
<p>Poi vediamo un simbolo <strong>@@ 1</strong> che descrive semplicemente che il <strong>diff</strong> è
partito dalla riga 1 a riportare la differenza fra le due versioni del documento.
Importanti sono i due spazi che troviamo fra il marcatore <strong>%[- MARK -]</strong> e
l'inizio della frase.</p>
<p>Qui avremo:</p>
<ul class="simple">
<li>un simbolo <strong>+</strong> che indica che questa linea è da aggiungere rispetto alla
precedente versione;</li>
<li>un simbolo <strong>-</strong> che indica che questa linea è da cancellare nella nuova versione
del documento.</li>
</ul>
<p>Le righe senza simbolo sono solo di contesto e servono ad aiutarci ad
individuare dove il documento è modificato tra le due versioni.</p>
<p>Il collaboratore, grazie al lavoro di confronto già svolto dallo script, basta
che intervenga nel documento solo sulle righe con questi due simboli!</p>
<p>Ovviamente non si interviene nella parte del documento con i marcatori <strong>%[- MARK -]</strong>
(questa deve rimanere inalterata affinché chi revisiona il documento abbia un
riferimento da cui partire!) ma direttamente nel testo del documento.</p>
<p>In particolare nell'esempio citato dobbiamo intervenire in queste righe</p>
<pre class="literal-block">
%[- 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:
</pre>
<p>Quelle con il simbolo <strong>-</strong> vanno rimosse e contestualmente aggiunte quelle con
il simbolo <strong>+</strong>.</p>
<p>Quindi questa parte del documento finale tradotto sarà la seguente:</p>
<pre class="literal-block">
\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.}
</pre>
<pre class="literal-block">
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}
...
</pre>
<p>Adesso si può procedere ad affrontare il <strong>DIFF 002 of 4</strong> cioè la seconda parte
del documento marcata e così via fino alla quarta.</p>
<p>Può capitare di trovare delle righe vuote precedute dal simbolo <strong>+</strong> o <strong>-</strong> a seconda
che siano da aggiungere o rimuovere. <strong>E' importante farlo anche se sono vuote!</strong></p>
<div class="section" id="file-nuovi-non-presenti-nella-precedente-versione">
<h2><a name="file-nuovi-non-presenti-nella-precedente-versione">File nuovi non presenti nella precedente versione</a></h2>
<p>Per quanto riguarda la traduzione dei file nuovi che non erano presenti nella
vecchia versione (quelli <strong>added</strong>) il procedimento è molto simile.</p>
<p>In particolare essi saranno suddivisi in pezzi da 100 righe per facilitare la
suddivisione del lavoro fra i vari traduttori.</p>
<p>All'inizio di ogni pezzetto da 100 righe ci sarà presente un marcatore del tipo
<strong>%[- MARK -] BEGIN PART 001 of 21</strong> che aiuta il collaboratore ad individuare
quale pezzetto tradurre.</p>
<p>Ovviamente tale marcatore non deve essere rimosso!</p>
<p>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.</p>
<p>Ecco a titolo di esempio come si presenta un documento prima della traduzione:</p>
<pre class="literal-block">
%[- 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.
...
</pre>
<p>e come diventa dopo:</p>
<pre class="literal-block">
%[- 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}.
...
</pre>
</div>
</div>
<div class="section" id="note-finali">
<h1><a name="note-finali">Note finali</a></h1>
<p>Una volta completato e ricontrollato il documento, lo si passa al coordinatore
oppure in allegato alla lista <a class="reference" href="mailto:docs@lists.python.it">docs@lists.python.it</a>.</p>
<p>In ogni caso è sempre bene
comunicare in lista il nome del documento tradotto/aggiornato con il suo
percorso completo.</p>
<p>Inoltre nel caso si presenti un qualunque dubbio di traduzione si usi il glossario
presente all'indirizzo <a class="reference" href="http://svn.python.it/admin/trunk/docs/glossario.xml">http://svn.python.it/admin/trunk/docs/glossario.xml</a>
oppure si chieda tranquillamente aiuto intervenendo in lista <a class="reference" href="mailto:docs@lists.python.it">docs@lists.python.it</a>.</p>
<p>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!</p>
</div>
<div class="section" id="file-dello-stato-delle-traduzioni">
<h1><a name="file-dello-stato-delle-traduzioni">File dello stato delle traduzioni</a></h1>
<p>E' stato creato un file situato all'indirizzo
<a class="reference" href="http://svn.python.it/admin/trunk/translations_status.xml">http://svn.python.it/admin/trunk/translations_status.xml</a> che tiene conto dello
stato di avanzamento delle traduzioni: in pratica chi ha tradotto cosa.</p>
<p>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.</p>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference" href="procedimento_passo_passo.ht">View document source</a>.
Generated on: 2006-10-23 05:36 UTC.
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>