Manuale del traduttore/revisore

Da Wiki di NetBSD Italia.

Questo articolo è solo un abbozzo, contribuisci a migliorarlo secondo le convenzioni di NetBSD-it mettendo a disposizione le tue conoscenze. La comunità te ne sarà grata!

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.

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. 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. Su vi 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;

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

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