Manuale del traduttore/revisore

Da Wiki di NetBSD Italia.

(Differenze fra le revisioni)
m (Prime operazioni: mi ero scordato il tag nowiki :-))
m (Bot: Sostituzione automatica (-a'([^']|$) +à\1))
Riga 58: Riga 58:
Questa sintassi è 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 più 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. Un ulteriore ''accorgimento'' di comodita'
+
la gestione dei file anche agli utenti meno pratici. Un ulteriore ''accorgimento'' di comodità
e' l'utilizzo della flag ''-d'' del comando ``checkout'' che consente di specificare la directory
e' l'utilizzo della flag ''-d'' del comando ``checkout'' che consente di specificare la directory
di destinazione dei file. Ad esempio, la guida di NetBSD puo' essere ottenuta anche cosi':
di destinazione dei file. Ad esempio, la guida di NetBSD puo' essere ottenuta anche cosi':
Riga 64: Riga 64:
  $ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs -d NetBSD-Guida -P netbsd/guida
  $ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs -d NetBSD-Guida -P netbsd/guida
-
Questo collochera' tutti i file nella directory ''NetBSD-Guida'' anziche' nella sottodirectory
+
Questo collocherà tutti i file nella directory ''NetBSD-Guida'' anziche' nella sottodirectory
''netbsd/guida''.
''netbsd/guida''.

Versione delle 09:35, 13 apr 2008

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 revisionisti 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 revisionisti è 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, eseguire il comando:

$ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs -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 -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à e' l'utilizzo della flag -d del comando ``checkout che consente di specificare la directory di destinazione dei file. Ad esempio, la guida di NetBSD puo' essere ottenuta anche cosi':

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

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

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 accentuati

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;. Per un elenco dei caratteri italiani più comuni consultare la tabella ISO 8859-1 (Latin-1).

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 digitate 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. Grosso modo un elenco più o meno utile (ma incompleto) è rappresentato così:

à è é ì ò ù

Non resta che mappare ogni carattere associandolo alla sua rispettiva entità XML.

Configurazione di GNU Emacs

XXX: per ragioni di coerenza e correttezza digitale (?) è il caso di considerare anche gli utenti GNU Emacs.

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.

Termini noti

XXX: spostare l'elenco dei termini in questo paragrafo?

Pubblicare il lavoro

Per coloro i quali non fossero traduttori e/o revisionisti ufficiale (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