Manuale del traduttore/revisore

Da Wiki di NetBSD Italia.

(Differenze fra le revisioni)
m (Configurazione di GNU Emacs)
m
 
(48 revisioni intermedie non mostrate.)
Riga 1: Riga 1:
-
{{stub}}
+
Questo testo si propone come ''manuale di riferimento'' per traduttori e revisori
-
 
+
-
Questo testo si propone come ''manuale di riferimento'' per traduttori e revisionisti
+
i quali hanno intenzione di lavorare su una delle guide messe a disposizione degli
i quali hanno intenzione di lavorare su una delle guide messe a disposizione degli
utenti [[NetBSD]] e [[pkgsrc]]. Le istruzioni sono relative a '''tutte''' le guide
utenti [[NetBSD]] e [[pkgsrc]]. Le istruzioni sono relative a '''tutte''' le guide
Riga 7: Riga 5:
== Introduzione ==
== Introduzione ==
-
Il formato utilizzato dalla guida di NetBSD e' XML/DocBook.
+
Il formato utilizzato dalla guida di NetBSD è XML/DocBook.
-
Come specificato nell'appendice B.1 della guida ufficiale '''non bisogna cominciare a
+
Come specificato nell'appendice B.1 della guida ufficiale non bisogna cominciare a
-
lavorare con HTML o altri formati: risultera' molto difficile convertire il tuo lavoro
+
lavorare con HTML o altri formati: risulterà molto difficile convertire il tuo lavoro
in XML/DocBook'''.
in XML/DocBook'''.
=== Adesione al progetto ===
=== Adesione al progetto ===
-
Il metodo piu' rapido per iscriversi al progetto NetBSDit-docs ottenendo cosi' accesso
+
Il metodo più rapido per iscriversi al progetto NetBSDit-docs ottenendo così accesso
in scrittura per il repository CVS in modo da poter pubblicare eventuali modifiche alla
in scrittura per il repository CVS in modo da poter pubblicare eventuali modifiche alla
-
documentazione, sara' sufficiente contattare il team di [[NetBSD Italia]] inviando una
+
documentazione, sarà sufficiente contattare il team di [[NetBSD Italia]] inviando una
email di richiesta (posibilmente con una breve lista dei documenti che sui quali si
email di richiesta (posibilmente con una breve lista dei documenti che sui quali si
-
desidera lavorare) a [[Utente:Claudio|Claudio M. Alessi]], [[Utente:leot|Leonardo Taccari]] oppure
+
desidera lavorare) a [[Utente:Clamiax|Claudio M. Alessi]], [[Utente:leot|Leonardo Taccari]] oppure
scrivendo un post direttamente nella lista di discussione ufficiale
scrivendo un post direttamente nella lista di discussione ufficiale
[http://mail-index.netbsd.org/netbsd-docs-it/tindex.html NetBSD-Docs-it]. In alternativa
[http://mail-index.netbsd.org/netbsd-docs-it/tindex.html NetBSD-Docs-it]. In alternativa
-
si puo' accedere al canale '''#NetBSD-it@Freenode''' per parlare direttamente con i membri
+
si può accedere al canale '''#NetBSD-it@Freenode''' per parlare direttamente con i membri
-
della comunita'. In questo caso si prega di non essere ''troppo'' formali :-)
+
della comunità. In questo caso si prega di non essere ''troppo'' formali :-)
== Scelta degli argomenti ==
== Scelta degli argomenti ==
-
Prima di cominciare a tradurre un documento e' buona norma verificare che questo sia
+
Prima di cominciare a tradurre un documento è buona norma verificare che questo sia
-
disponibile per la traduzione. Infatti, qualcun altro potrebbe essere gia' impegnato
+
disponibile per la traduzione. Infatti, qualcun altro potrebbe essere già impegnato
-
nella traduzione di un determinato argomento o questo potrebbe essere gia' stato tradotto.
+
nella traduzione di un determinato argomento o questo potrebbe essere già stato tradotto.
Di norma comunque, i documenti tradotti (o in fase di traduzione) vengono mantenuti quanto
Di norma comunque, i documenti tradotti (o in fase di traduzione) vengono mantenuti quanto
-
piu' aggiornati possibile sul repository CVS.
+
più aggiornati possibile sul repository CVS.
-
Una lista completa di documenti e dei relativi traduttori e revisionisti e' stata
+
Una lista completa di documenti e dei relativi traduttori e revisori è stata
disposta in una tabella, consultabile nella pagina di coordinamento per le
disposta in una tabella, consultabile nella pagina di coordinamento per le
[[traduzioni]]. Si consiglia di considerare inoltre l'idea di ''postare'' su
[[traduzioni]]. Si consiglia di considerare inoltre l'idea di ''postare'' su
-
'''netbsd-docs-it'' per chiarimenti, richieste, commenti e altro.
+
'''netbsd-docs-it''' per chiarimenti, richieste, commenti e altro.
Una volta scelto l'argomento da tradurre (o revisionare) bisogna provvedere a modificare
Una volta scelto l'argomento da tradurre (o revisionare) bisogna provvedere a modificare
Riga 39: Riga 37:
== Ottenere i sorgenti ==
== Ottenere i sorgenti ==
I file necessari per lavorare a una traduzione si possono ottenere direttamente dai
I file necessari per lavorare a una traduzione si possono ottenere direttamente dai
-
repository ufficiali del progetto [http://netbsdit.docs.sf.net NetBSDit-docs]. Per
+
repository ufficiali del progetto [http://netbsdit-docs.sf.net NetBSDit-docs]. Per
-
ottenere la guida di NetBSD, che attualmente e' quella con maggiore priorita' nella
+
ottenere la guida di NetBSD, che attualmente è quella con maggiore priorità nella
-
lista delle [[traduzioni]], eseguire il comando:
+
lista delle [[traduzioni]], assicurarsi di avere accesso in lettura ed esecuzione
 +
su tutte le directory del percorso di destinazione (in sintesi ognuna delle directory
 +
mostrata nell'output di {{man|pwd|1}}, specificando la flag -P) ed eseguire il comando:
-
  $ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs -P netbsd/guida
+
  $ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs co -P netbsd/guida
-
In questo modo verra' creata la directory ''netbsd'' contenente tutti i file XML (tradotti
+
In questo modo verrà creata la directory ''netbsd/guida'' contenente tutti i file XML (tradotti
e non) della guida ufficiale, ''The NetBSD Guide'', i quali potranno essere modificati per
e non) della guida ufficiale, ''The NetBSD Guide'', i quali potranno essere modificati per
effettuare successivamente (ed eventualmente) un ''commit'' sul repository CVS.
effettuare successivamente (ed eventualmente) un ''commit'' sul repository CVS.
Riga 54: Riga 54:
questo modo:
questo modo:
-
  $ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs -P software/guida-prova
+
  $ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs co -P software/guida-prova
-
Questa sintassi e' dovuta alla struttura ''ad albero'' del repository su cui risiedono
+
Questa sintassi è dovuta alla struttura ''ad albero'' del repository su cui risiedono
-
i sorgenti, i quali sono distribuiti in modo da rendere quanto piu' semplice possibile
+
i sorgenti, i quali sono distribuiti in modo da rendere quanto più semplice possibile
-
la gestione dei file anche agli utenti meno pratici.
+
la gestione dei file anche agli utenti meno pratici. Un ulteriore ''accorgimento'' di comodità
 +
è l'utilizzo della flag ''-d'' del comando ``checkout'' che consente di specificare la directory
 +
di destinazione dei file. Ad esempio, la guida di NetBSD può essere ottenuta anche così:
 +
 
 +
$ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs co -d NetBSD-Guida -P netbsd/guida
 +
 
 +
Questo collocherà tutti i file nella directory ''NetBSD-Guida'' anzichè nella sottodirectory
 +
''netbsd/guida''.
 +
 
 +
Nel caso in cui a dover ottenere i sorgenti sia un traduttore/revisore con accesso in scrittura
 +
ai repository CVS il comando varia leggermente, sostituendo "pserver" con "ext" e "anonymous" con
 +
il nome utente effettivo di [http://sf.net/ SourceForge.net], come segue:
 +
 
 +
$ cvs -d :ext:nome_utente@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs co -d NetBSD-Guida -P netbsd/guida
 +
 
 +
A questo punto sarà possibile effettuare dei commit.
 +
 
 +
=== Sorgenti ufficiali ===
 +
Talvolta, puo' risultare utile ottenere i sorgenti ufficiali al fine di effettuare una
 +
revisione, un aggiornamento o anche per cominciare a lavorare alla traduzione di un nuovo
 +
capitolo introdotto nella documentazione ufficiale, il quale non e' ancora stato importanto
 +
nei repository del progetto NetBSDit-docs. Una volta terminata la traduzione si potra' importare
 +
direttamente la versione tradotta. In questo caso bastera' eseguire il seguente comando per
 +
ottenere i sorgenti ufficiali in inglese:
 +
 
 +
$ cvs -d :pserver:anoncvs@anoncvs.NetBSD.org:/cvsroot co -d NetBSD-Guide-EN -P htdocs/docs/guide/en
 +
 
 +
Oltre ai file xml saranno ottenute anche le copie html e alcune directory
 +
inutilizzate.  E' anche possibile consultare i sorgenti
 +
[http://cvsweb.netbsd.org/bsdweb.cgi/htdocs/docs/internals/en/ direttamente sul web].
 +
 
 +
=== Pulizia ===
 +
Per ripulire la directory lasciando al suo interno solo i file xml, basta
 +
entrare nella directory ''NetBSD-Guide-EN'' ed eseguire il seguente comando:
 +
 
 +
$ rm -rf CVS Makefile share *.[!x]*
 +
 
 +
A questo punto si potranno utilizzare i sorgenti per qualsiasi scopo tenendo a mente che eventuali
 +
modifiche a quest'ultimi non si potranno caricare sui repository ufficiali di [[NetBSD]], bensi'
 +
su quelli del progetto NetBSDit-docs.
== Modificare i file ==
== Modificare i file ==
-
Per il processo di modifica tutto cio' di cui si necessita sono i sorgenti delle pagine
+
Per il processo di modifica tutto ciò di cui si necessita sono i sorgenti delle pagine
che si intende modificare e un semplice editor di testi ''puro'', quindi esclusi OpenOffice,
che si intende modificare e un semplice editor di testi ''puro'', quindi esclusi OpenOffice,
-
KWord e simili. Piuttosto utilizzare software decenti come {{man|vi|1}} che e' incluso nel
+
KWord e simili. Piuttosto utilizzare software decenti come {{man|vi|1}} che è incluso nel
sistema base o ancora meglio {{pkgsrc|editors|vim}} o {{pkgsrc|editors|emacs}} (giusto
sistema base o ancora meglio {{pkgsrc|editors|vim}} o {{pkgsrc|editors|emacs}} (giusto
per nominarne alcuni).
per nominarne alcuni).
 +
 +
=== Prime operazioni ===
 +
La prima operazione da fare è modificare il tag RCS in modo tale che per le future manutenzioni si conosce la versione da cui la traduzione è basata, ad esempio nel file non tradotto:
 +
 +
<nowiki><!-- $NetBSD: chap-intro.xml,v 1.3 2007/08/05 13:43:56 kano Exp $ --></nowiki>
 +
 +
Nel file tradotto invece:
 +
 +
<nowiki><!-- $NetBSD$ --></nowiki>
 +
<nowiki><!-- Based on english version: --></nowiki>
 +
<nowiki><!-- NetBSD: chap-intro.xml,v 1.3 2007/08/05 13:43:56 kano Exp $ --></nowiki>
 +
 +
Notare il primo ''$'' assente nel file tradotto in modo tale da non rendere l'ultima riga un tag valido per RCS.
=== Regole di formattazione ===
=== Regole di formattazione ===
Riga 72: Riga 124:
* 2 spazi per indentare il codice. Non sono ammessi tab o sequenze di spazi diverse da 2;
* 2 spazi per indentare il codice. Non sono ammessi tab o sequenze di spazi diverse da 2;
-
* linee lunghe non piu' di 72 caratteri;
+
* linee lunghe non più di 72 caratteri;
* delle linee di separazione (commenti) fra 2 sezioni differenti.
* delle linee di separazione (commenti) fra 2 sezioni differenti.
Riga 78: Riga 130:
della guida ufficiale.
della guida ufficiale.
-
=== Caratteri accentuati ===
+
=== Caratteri accentati ===
Il processo di traduzione non richiede necessariamente la conoscenza del linguaggio di
Il processo di traduzione non richiede necessariamente la conoscenza del linguaggio di
markup XML ma solo di alcuni accorgimenti per altro comuni a tutti i linguaggi derivati
markup XML ma solo di alcuni accorgimenti per altro comuni a tutti i linguaggi derivati
-
come l'(X)HTML. Fondamentalmente l'unica cura che bisogna avere e' di rimpiazzare i
+
come l'(X)HTML. Fondamentalmente l'unica cura che bisogna avere è di rimpiazzare i
caratteri accentuati con le relative ''entità'' XML. Questo vuol dire che caratteri come
caratteri accentuati con le relative ''entità'' XML. Questo vuol dire che caratteri come
''è'', ''à'' o ''ì'' vanno rimpiazzati con le relative entità, rispettivamente: ''&amp;egrave;'',
''è'', ''à'' o ''ì'' vanno rimpiazzati con le relative entità, rispettivamente: ''&amp;egrave;'',
-
''&amp;agrave;'' e ''&amp;igrave;''. Per un elenco dei caratteri italiani piu' comuni consultare
+
''&amp;agrave;'' e ''&amp;igrave;''. La tabella
-
la tabella [http://www.w3schools.com/tags/ref_entities.asp ISO 8859-1 (Latin-1)].
+
[http://www.w3schools.com/tags/ref_entities.asp ISO 8859-1 (Latin-1)] fornisce una vasta gamma
 +
di caratteri accentati e le relative entita' XML alla quale questi sono associati. Per un elenco
 +
dei caratteri piu' comuni fare riferimento alla seguente tabella:
 +
 
 +
<blockquote style="background: white; border: 1px solid rgb(153, 153, 153); padding: 1em;">
 +
{| class="wikitable sortable"
 +
|+Tabella delle associazioni
 +
|-
 +
! Carattere !! Entità XML
 +
|-
 +
| É || &amp;Eacute;
 +
|-
 +
| à || &amp;agrave;
 +
|-
 +
| è || &amp;egrave;
 +
|-
 +
| é || &amp;eacute;
 +
|-
 +
| ì || &amp;igrave;
 +
|-
 +
| ò || &amp;ograve;
 +
|-
 +
| ù || &amp;ugrave
 +
|}
 +
</blockquote>
 +
 
 +
Di seguito vengono fornite alcune istruzioni basilari per mettere a punto i due piu' diffusi
 +
editor di testo: Vi (o Vim) e GNU Emacs. Per chi non avesse la possibilita' di effettuare
 +
queste sostituzioni direttamente dal proprio editor di testo e' possibile utilizzare un metodo
 +
alternativo sfruttando un [[#Utilizzare un editor in-line|editor inline]].
==== Configurazione di Vi/Vim ====
==== Configurazione di Vi/Vim ====
-
Fra le varie funzionalita', l'editor vi (e derivati) offre la possibilita' di rimpiazzare
+
Fra le varie funzionalità, l'editor vi (e derivati) offre la possibilità di
-
automaticamente del testo al momento in cui lo si digita. Questo risulta molto utile quando
+
rimpiazzare automaticamente del testo al momento in cui lo si digita. Questo
-
si lavora su documenti in cui alcuni caratteri vanno rimpiazzati praticamente sempre. Anziche'
+
risulta molto utile quando si lavora su documenti in cui alcuni caratteri vanno
-
[[#utilizzare un editor in-line]] '''dopo''' la stesura del testo e' conveniente farlo durante
+
rimpiazzati praticamente sempre.
-
il processo di traduzione risparmiando un po' tempo. Su vi tutto quello che bisogna fare e'
+
Anzichè [[#Utilizzare un editor in-line|utilizzare un editor in-line]]
-
''mappare'' ogni singolo rimpiazzo eseguendo in modalita' ''comando'' (command-mode) quanto
+
'''dopo''' la stesura del testo è conveniente farlo durante il processo di
-
segue:
+
traduzione risparmiando un tempo. Tutto quello che bisogna fare è
 +
''mappare'' ogni singolo rimpiazzo eseguendo in modalità ''comando''
 +
(command-mode) quanto segue:
  :map! vecchio nuovo
  :map! vecchio nuovo
-
Dove ''vecchio'' corrisponde al testo digitate e ''nuovo'' al rimpiazzo che verra' utilizzato
+
Dove ''vecchio'' corrisponde al testo digitato e ''nuovo'' al rimpiazzo che verrà utilizzato
automaticamente. Quindi ad esempio, per rimpiazzare automaticamente ogni volta che viene
automaticamente. Quindi ad esempio, per rimpiazzare automaticamente ogni volta che viene
digitato il carattere accentuato ''è'' con la stringa ''&amp;egrave;'' basta eseguire il comando:
digitato il carattere accentuato ''è'' con la stringa ''&amp;egrave;'' basta eseguire il comando:
Riga 104: Riga 187:
  :map! è &amp;egrave;
  :map! è &amp;egrave;
-
E' cosi' via per tutte le altre entita' XML necessarie. Grosso modo un elenco piu' o meno
+
E così via per tutte le altre entità XML necessarie. Per una lista delle
-
utile (ma incompleto) e' rappresentato cosi':
+
entita' piu' comuni fare riferimento alla [[#Caratteri accentati|precedente tabella]].
-
 
+
-
à è é ì ò ù
+
-
 
+
-
Non resta che ''mappare'' ogni carattere associandolo alla sua rispettiva entita' XML.
+
-
==== Configurazione di GNU Emacs ====
+
Cosí facendo l'editor produrrá una leggera latenza in modalitá inserimento.
-
'''XXX''': per ragioni di coerenza e correttezza digitale (?) e' il caso di considerare anche gli utenti GNU Emacs.
+
Attualmente non c'è soluzione al problema.  Nel caso in cui si utilizzi Vim, è
 +
possibile utilizzare la funzionalita ":abbr" o meglio ancora i cosiddetti
 +
"digraphs". Si rimanda alla documentazione di Vim per maggiori informazioni.
==== Utilizzare un editor in-line ====
==== Utilizzare un editor in-line ====
-
L'approfondimento di tali strumenti e' delegato a documenti appositi. Questo paragrafo
+
L'approfondimento di tali strumenti è delegato a documenti appositi. Questo paragrafo
-
mostrera' semplicemente un esempio (il piu' semplice) di rimpiazzamento testuale al fine
+
mostrerà semplicemente un esempio (il più semplice) di rimpiazzamento testuale al fine
di stimolare gli utenti meno pratici a non effettuare noiose sostituzioni a mano una per
di stimolare gli utenti meno pratici a non effettuare noiose sostituzioni a mano una per
-
una optando invece per una soluzione piu' elegante, comoda e rapida. Il seguente comando
+
una optando invece per una soluzione più elegante, comoda e rapida. Il seguente comando
-
rimpiazza tutte le occorrenze del carattere ''ù'' con la relativa entita' XML, ''&amp;ugrave;''
+
rimpiazza tutte le occorrenze del carattere ''ù'' con la relativa entità XML, ''&amp;ugrave;'',
-
nel file chap-edit.xml:
+
nel file ''chap-edit.xml'':
  $ sed 's/ù/\&amp;ugrave;/g' < chap-edit.xml > chap-edit.xml.entity
  $ sed 's/ù/\&amp;ugrave;/g' < chap-edit.xml > chap-edit.xml.entity
Riga 131: Riga 212:
il precedente (secondo comando). Altri caratteri possono essere rimpiazzati utilizzando
il precedente (secondo comando). Altri caratteri possono essere rimpiazzati utilizzando
la flag ''-e'' o in modo analogo eseguendo {{man|sed|1}} una volta per ogni carattere.
la flag ''-e'' o in modo analogo eseguendo {{man|sed|1}} una volta per ogni carattere.
-
 
-
=== Termini noti ===
 
-
'''XXX''': spostare l'elenco dei [[Traduzioni#Termini|termini]] in questo paragrafo?
 
== Pubblicare il lavoro ==
== Pubblicare il lavoro ==
-
Per coloro i quali non fossero traduttori e/o revisionisti ufficiale (quindi senza accesso
+
Per coloro i quali non fossero traduttori e/o revisori ufficiali (quindi senza accesso
-
ai repository del progetto NetBSDit-docs) e' consigliato rimediare un account
+
ai repository del progetto NetBSDit-docs) è consigliato rimediare un account
-
[[#Adesione al progetto|aderendo al progetto]] come descritto sopra. In alternativa e'
+
[[#Adesione al progetto|aderendo al progetto]] come descritto sopra. In alternativa è
possibile contattare direttamente un membro del progetto al fine di delegare a lui il
possibile contattare direttamente un membro del progetto al fine di delegare a lui il
-
''commit'' della documentazione attualmente tradotta. In questo caso sara' sufficiente
+
''commit'' della documentazione attualmente tradotta. In questo caso sarà sufficiente
inviargli un tarball contenente i file XML tradotti ma, banale a dirsi, non prima di averlo
inviargli un tarball contenente i file XML tradotti ma, banale a dirsi, non prima di averlo
adeguatamente informato.
adeguatamente informato.
-
Per effettuare un commit tutto quello che si deve fare e' eseguire il seguente comando:
+
Per effettuare un commit tutto quello che si deve fare è eseguire il seguente comando:
  $ cvs ci -m "Descrizione delle modifiche apportate."
  $ cvs ci -m "Descrizione delle modifiche apportate."
Riga 150: Riga 228:
In questo modo '''tutti''' i file aggiornati, ovvero quelli che non corrisponderanno alla
In questo modo '''tutti''' i file aggiornati, ovvero quelli che non corrisponderanno alla
versione presente nel repository CVS, verranno caricati sul server rimpiazzando quelli
versione presente nel repository CVS, verranno caricati sul server rimpiazzando quelli
-
vecchi. E' possibile anche specificare una lista di file da aggiornare in modo da ignorare
+
vecchi. È possibile anche specificare una lista di file da aggiornare in modo da ignorare
temporaneamente tutte le eventuali altre modifiche, come segue:
temporaneamente tutte le eventuali altre modifiche, come segue:
  $ cvs ci -m "Corretto un errore di battitura." chap-edit.xml
  $ cvs ci -m "Corretto un errore di battitura." chap-edit.xml
-
Cosi' facendo verra' aggiornato solo il file ''chap-edit.xml''.
+
Così facendo verrà aggiornato solo il file ''chap-edit.xml''.
Una volta terminata una traduzione, ricordarsi di cambiare lo stato nella riga relativa
Una volta terminata una traduzione, ricordarsi di cambiare lo stato nella riga relativa
al file nella tabella delle [[traduzioni]].
al file nella tabella delle [[traduzioni]].
Riga 162: Riga 240:
Una solida organizzazione accompagnata dalla potenza di avanzati software per il
Una solida organizzazione accompagnata dalla potenza di avanzati software per il
''versioning'' semplifica di molto lo sviluppo di qualsiasi progetto. Tuttavia, dal momento
''versioning'' semplifica di molto lo sviluppo di qualsiasi progetto. Tuttavia, dal momento
-
che si ha a che fare con file in formato XML, i quali possono creare un po' di confusione, e'
+
che si ha a che fare con file in formato XML, i quali possono creare un di confusione, è
-
bene seguire poche linee guide al fine di essere quanto piu' efficienti possibili. In
+
bene seguire poche linee guide al fine di essere quanto più efficienti possibili. In
-
particolar modo per i ''nuovi arrivati'' e' consigliato:
+
particolar modo per i ''nuovi arrivati'' è consigliato:
-
* Modificare un file alla volta. Evitare di cominciare a tradurre altri file finche' quello corrente non sia stato ultimato. Questo puo' evitare confusioni o, qualora piu' traduttori stiano lavorando agli stessi file, puo' minimizzare i conflitti nel repository;
+
* Modificare un file alla volta. Evitare di cominciare a tradurre altri file finchè quello corrente non sia stato ultimato. Questo può evitare confusioni o, qualora più traduttori stiano lavorando agli stessi file, può minimizzare i conflitti nel repository;
-
* Ove possibile, cercare sempre di concludere le sequenze logiche di testo. In termini pratici questo significha di concludere una traduzione in un unico processo di ''editing'' evitando di suddividere nel tempo modifiche relative allo stesso capitolo. Sebbene i file (quindi i capitoli) siano piuttosto grossi e' buona norma cercare di seguire questa regola riferendosi quanto meno ai paragrafi;
+
* Ove possibile, cercare sempre di concludere le sequenze logiche di testo. In termini pratici questo significha di concludere una traduzione in un unico processo di ''editing'' evitando di suddividere nel tempo modifiche relative allo stesso capitolo. Sebbene i file (quindi i capitoli) siano piuttosto grossi è buona norma cercare di seguire questa regola riferendosi quanto meno ai paragrafi;
* Effettuare tempestivamente il commit al fine di assicurare il completo salvataggio della documentazione tradotta fino a quel momento. Questo riduce i rischi di perdite e consente di riprendere il lavoro anche da altre postazioni semplicemente scaricando la versione del documento presente nel repository;
* Effettuare tempestivamente il commit al fine di assicurare il completo salvataggio della documentazione tradotta fino a quel momento. Questo riduce i rischi di perdite e consente di riprendere il lavoro anche da altre postazioni semplicemente scaricando la versione del documento presente nel repository;
-
* Cos'altro?
 
   
   
-
Si ricorda inoltre agli utenti avanzati che e' possibile fornire della '''nuova'''
+
Si ricorda inoltre agli utenti avanzati che è possibile fornire della '''nuova'''
documentazione al fine di estendere le guide ufficiali.
documentazione al fine di estendere le guide ufficiali.
== Collegamenti esterni ==
== Collegamenti esterni ==
* [http://netbsdit-docs.sf.net/ Sito ufficiale del progetto NetBSDit-docs]
* [http://netbsdit-docs.sf.net/ Sito ufficiale del progetto NetBSDit-docs]
-
* [http://netbsd.org/docs/guide/en/ap-xml.html#ap-xml-links appendice C.5 (links)] della [http://netbsd.org/docs/guide/en guida ufficiale].
+
* [http://netbsd.org/docs/guide/en/ap-xml.html#ap-xml-links appendice C.5 (links)] della [http://netbsd.org/docs/guide/en guida ufficiale]
* [http://www.netbsd.org/developers/translate.html Pagina riguardante la traduzione di htdocs] del [http://www.netbsd.org sito ufficiale]
* [http://www.netbsd.org/developers/translate.html Pagina riguardante la traduzione di htdocs] del [http://www.netbsd.org sito ufficiale]
 +
* [http://netbsdit-docs.cvs.sourceforge.net/viewvc/netbsdit-docs/ Sorgenti sul web]
 +
* [http://cvsweb.netbsd.org/bsdweb.cgi/htdocs/docs/ Sorgenti ufficiali sul web (en)]
 +
 +
[[Categoria:Documenti]]

Versione corrente delle 22:19, 29 mar 2010

Questo testo si propone come manuale di riferimento per traduttori e revisori i quali hanno intenzione di lavorare su una delle guide messe a disposizione degli utenti NetBSD e pkgsrc. Le istruzioni sono relative a tutte le guide (correlate al progetto NetBSD), non solo The NetBSD Guide.

Indice

Introduzione

Il formato utilizzato dalla guida di NetBSD è XML/DocBook. Come specificato nell'appendice B.1 della guida ufficiale non bisogna cominciare a lavorare con HTML o altri formati: risulterà molto difficile convertire il tuo lavoro in XML/DocBook.

Adesione al progetto

Il metodo più rapido per iscriversi al progetto NetBSDit-docs ottenendo così accesso in scrittura per il repository CVS in modo da poter pubblicare eventuali modifiche alla documentazione, sarà sufficiente contattare il team di NetBSD Italia inviando una email di richiesta (posibilmente con una breve lista dei documenti che sui quali si desidera lavorare) a Claudio M. Alessi, Leonardo Taccari oppure scrivendo un post direttamente nella lista di discussione ufficiale NetBSD-Docs-it. In alternativa si può accedere al canale #NetBSD-it@Freenode per parlare direttamente con i membri della comunità. In questo caso si prega di non essere troppo formali :-)

Scelta degli argomenti

Prima di cominciare a tradurre un documento è buona norma verificare che questo sia disponibile per la traduzione. Infatti, qualcun altro potrebbe essere già impegnato nella traduzione di un determinato argomento o questo potrebbe essere già stato tradotto. Di norma comunque, i documenti tradotti (o in fase di traduzione) vengono mantenuti quanto più aggiornati possibile sul repository CVS. Una lista completa di documenti e dei relativi traduttori e revisori è stata disposta in una tabella, consultabile nella pagina di coordinamento per le traduzioni. Si consiglia di considerare inoltre l'idea di postare su netbsd-docs-it per chiarimenti, richieste, commenti e altro.

Una volta scelto l'argomento da tradurre (o revisionare) bisogna provvedere a modificare appropriatamente la relativa voce nella tabella all'interno della pagina Traduzioni.

Ottenere i sorgenti

I file necessari per lavorare a una traduzione si possono ottenere direttamente dai repository ufficiali del progetto NetBSDit-docs. Per ottenere la guida di NetBSD, che attualmente è quella con maggiore priorità nella lista delle traduzioni, assicurarsi di avere accesso in lettura ed esecuzione su tutte le directory del percorso di destinazione (in sintesi ognuna delle directory mostrata nell'output di pwd(1), specificando la flag -P) ed eseguire il comando:

$ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs co -P netbsd/guida

In questo modo verrà creata la directory netbsd/guida contenente tutti i file XML (tradotti e non) della guida ufficiale, The NetBSD Guide, i quali potranno essere modificati per effettuare successivamente (ed eventualmente) un commit sul repository CVS.

Per ottenere i sorgenti XML relativi ad altri documenti basta seguire la stessa procedura cambiando solo il percorso. In generale, per ottenere i sorgenti del documento guida-prova relativa a software (al momento solo NetBSD o pkgsrc) basta eseguire cvs(1) in questo modo:

$ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs co -P software/guida-prova

Questa sintassi è dovuta alla struttura ad albero del repository su cui risiedono i sorgenti, i quali sono distribuiti in modo da rendere quanto più semplice possibile la gestione dei file anche agli utenti meno pratici. Un ulteriore accorgimento di comodità è l'utilizzo della flag -d del comando ``checkout che consente di specificare la directory di destinazione dei file. Ad esempio, la guida di NetBSD può essere ottenuta anche così:

$ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs co -d NetBSD-Guida -P netbsd/guida

Questo collocherà tutti i file nella directory NetBSD-Guida anzichè nella sottodirectory netbsd/guida.

Nel caso in cui a dover ottenere i sorgenti sia un traduttore/revisore con accesso in scrittura ai repository CVS il comando varia leggermente, sostituendo "pserver" con "ext" e "anonymous" con il nome utente effettivo di SourceForge.net, come segue:

$ cvs -d :ext:nome_utente@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs co -d NetBSD-Guida -P netbsd/guida

A questo punto sarà possibile effettuare dei commit.

Sorgenti ufficiali

Talvolta, puo' risultare utile ottenere i sorgenti ufficiali al fine di effettuare una revisione, un aggiornamento o anche per cominciare a lavorare alla traduzione di un nuovo capitolo introdotto nella documentazione ufficiale, il quale non e' ancora stato importanto nei repository del progetto NetBSDit-docs. Una volta terminata la traduzione si potra' importare direttamente la versione tradotta. In questo caso bastera' eseguire il seguente comando per ottenere i sorgenti ufficiali in inglese:

$ cvs -d :pserver:anoncvs@anoncvs.NetBSD.org:/cvsroot co -d NetBSD-Guide-EN -P htdocs/docs/guide/en

Oltre ai file xml saranno ottenute anche le copie html e alcune directory inutilizzate. E' anche possibile consultare i sorgenti direttamente sul web.

Pulizia

Per ripulire la directory lasciando al suo interno solo i file xml, basta entrare nella directory NetBSD-Guide-EN ed eseguire il seguente comando:

$ rm -rf CVS Makefile share *.[!x]*

A questo punto si potranno utilizzare i sorgenti per qualsiasi scopo tenendo a mente che eventuali modifiche a quest'ultimi non si potranno caricare sui repository ufficiali di NetBSD, bensi' su quelli del progetto NetBSDit-docs.

Modificare i file

Per il processo di modifica tutto ciò di cui si necessita sono i sorgenti delle pagine che si intende modificare e un semplice editor di testi puro, quindi esclusi OpenOffice, KWord e simili. Piuttosto utilizzare software decenti come vi(1) che è incluso nel sistema base o ancora meglio editors/vim o editors/emacs (giusto per nominarne alcuni).

Prime operazioni

La prima operazione da fare è modificare il tag RCS in modo tale che per le future manutenzioni si conosce la versione da cui la traduzione è basata, ad esempio nel file non tradotto:

<!-- $NetBSD: chap-intro.xml,v 1.3 2007/08/05 13:43:56 kano Exp $ -->

Nel file tradotto invece:

<!-- $NetBSD$ -->
<!-- Based on english version: -->
<!-- NetBSD: chap-intro.xml,v 1.3 2007/08/05 13:43:56 kano Exp $ -->

Notare il primo $ assente nel file tradotto in modo tale da non rendere l'ultima riga un tag valido per RCS.

Regole di formattazione

Il team di NetBSD fornisce alcune regole da seguire al fine di rendere i sorgenti compatti e facilmente comprensibili. In particolare bisogna utilizzare:

  • 2 spazi per indentare il codice. Non sono ammessi tab o sequenze di spazi diverse da 2;
  • linee lunghe non più di 72 caratteri;
  • delle linee di separazione (commenti) fra 2 sezioni differenti.

Per un esempio di documento XML/DocBook consultare l'appendice B.3 della guida ufficiale.

Caratteri accentati

Il processo di traduzione non richiede necessariamente la conoscenza del linguaggio di markup XML ma solo di alcuni accorgimenti per altro comuni a tutti i linguaggi derivati come l'(X)HTML. Fondamentalmente l'unica cura che bisogna avere è di rimpiazzare i caratteri accentuati con le relative entità XML. Questo vuol dire che caratteri come è, à o ì vanno rimpiazzati con le relative entità, rispettivamente: &egrave;, &agrave; e &igrave;. La tabella ISO 8859-1 (Latin-1) fornisce una vasta gamma di caratteri accentati e le relative entita' XML alla quale questi sono associati. Per un elenco dei caratteri piu' comuni fare riferimento alla seguente tabella:

Tabella delle associazioni
Carattere Entità XML
É &Eacute;
à &agrave;
è &egrave;
é &eacute;
ì &igrave;
ò &ograve;
ù &ugrave

Di seguito vengono fornite alcune istruzioni basilari per mettere a punto i due piu' diffusi editor di testo: Vi (o Vim) e GNU Emacs. Per chi non avesse la possibilita' di effettuare queste sostituzioni direttamente dal proprio editor di testo e' possibile utilizzare un metodo alternativo sfruttando un editor inline.

Configurazione di Vi/Vim

Fra le varie funzionalità, l'editor vi (e derivati) offre la possibilità di rimpiazzare automaticamente del testo al momento in cui lo si digita. Questo risulta molto utile quando si lavora su documenti in cui alcuni caratteri vanno rimpiazzati praticamente sempre. Anzichè utilizzare un editor in-line dopo la stesura del testo è conveniente farlo durante il processo di traduzione risparmiando un pò tempo. Tutto quello che bisogna fare è mappare ogni singolo rimpiazzo eseguendo in modalità comando (command-mode) quanto segue:

:map! vecchio nuovo

Dove vecchio corrisponde al testo digitato e nuovo al rimpiazzo che verrà utilizzato automaticamente. Quindi ad esempio, per rimpiazzare automaticamente ogni volta che viene digitato il carattere accentuato è con la stringa &egrave; basta eseguire il comando:

:map! è &egrave;

E così via per tutte le altre entità XML necessarie. Per una lista delle entita' piu' comuni fare riferimento alla precedente tabella.

Cosí facendo l'editor produrrá una leggera latenza in modalitá inserimento. Attualmente non c'è soluzione al problema. Nel caso in cui si utilizzi Vim, è possibile utilizzare la funzionalita ":abbr" o meglio ancora i cosiddetti "digraphs". Si rimanda alla documentazione di Vim per maggiori informazioni.

Utilizzare un editor in-line

L'approfondimento di tali strumenti è delegato a documenti appositi. Questo paragrafo mostrerà semplicemente un esempio (il più semplice) di rimpiazzamento testuale al fine di stimolare gli utenti meno pratici a non effettuare noiose sostituzioni a mano una per una optando invece per una soluzione più elegante, comoda e rapida. Il seguente comando rimpiazza tutte le occorrenze del carattere ù con la relativa entità XML, &ugrave;, nel file chap-edit.xml:

$ sed 's/ù/\&ugrave;/g' < chap-edit.xml > chap-edit.xml.entity
$ mv chap-edit.xml.entity chap-edit.xml

Il carattere & essendo riservato a sed(1) necessita di un ulteriore carattere cosiddetto di escape, ovvero '\'. Riassumendo: i due comandi non fanno altro che rimpiazzare tutte le occorrenze (come descritto sopra) e salvare il risultato nel file chap-edit.xml.entity il quale viene poi rinominato in chap-edit.xml, sostituendo il precedente (secondo comando). Altri caratteri possono essere rimpiazzati utilizzando la flag -e o in modo analogo eseguendo sed(1) una volta per ogni carattere.

Pubblicare il lavoro

Per coloro i quali non fossero traduttori e/o revisori ufficiali (quindi senza accesso ai repository del progetto NetBSDit-docs) è consigliato rimediare un account aderendo al progetto come descritto sopra. In alternativa è possibile contattare direttamente un membro del progetto al fine di delegare a lui il commit della documentazione attualmente tradotta. In questo caso sarà sufficiente inviargli un tarball contenente i file XML tradotti ma, banale a dirsi, non prima di averlo adeguatamente informato.

Per effettuare un commit tutto quello che si deve fare è eseguire il seguente comando:

$ cvs ci -m "Descrizione delle modifiche apportate."

In questo modo tutti i file aggiornati, ovvero quelli che non corrisponderanno alla versione presente nel repository CVS, verranno caricati sul server rimpiazzando quelli vecchi. È possibile anche specificare una lista di file da aggiornare in modo da ignorare temporaneamente tutte le eventuali altre modifiche, come segue:

$ cvs ci -m "Corretto un errore di battitura." chap-edit.xml

Così facendo verrà aggiornato solo il file chap-edit.xml. Una volta terminata una traduzione, ricordarsi di cambiare lo stato nella riga relativa al file nella tabella delle traduzioni.

Suggerimenti e consigli

Una solida organizzazione accompagnata dalla potenza di avanzati software per il versioning semplifica di molto lo sviluppo di qualsiasi progetto. Tuttavia, dal momento che si ha a che fare con file in formato XML, i quali possono creare un pò di confusione, è bene seguire poche linee guide al fine di essere quanto più efficienti possibili. In particolar modo per i nuovi arrivati è consigliato:

  • Modificare un file alla volta. Evitare di cominciare a tradurre altri file finchè quello corrente non sia stato ultimato. Questo può evitare confusioni o, qualora più traduttori stiano lavorando agli stessi file, può minimizzare i conflitti nel repository;
  • Ove possibile, cercare sempre di concludere le sequenze logiche di testo. In termini pratici questo significha di concludere una traduzione in un unico processo di editing evitando di suddividere nel tempo modifiche relative allo stesso capitolo. Sebbene i file (quindi i capitoli) siano piuttosto grossi è buona norma cercare di seguire questa regola riferendosi quanto meno ai paragrafi;
  • Effettuare tempestivamente il commit al fine di assicurare il completo salvataggio della documentazione tradotta fino a quel momento. Questo riduce i rischi di perdite e consente di riprendere il lavoro anche da altre postazioni semplicemente scaricando la versione del documento presente nel repository;

Si ricorda inoltre agli utenti avanzati che è possibile fornire della nuova documentazione al fine di estendere le guide ufficiali.

Collegamenti esterni

Strumenti personali