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 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 e' XML/DocBook. 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 in XML/DocBook.
Adesione al progetto
Il metodo piu' rapido per iscriversi al progetto NetBSDit-docs ottenendo cosi' accesso 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 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 puo' accedere al canale #NetBSD-it@Freenode per parlare direttamente con i membri della comunita'. In questo caso si prega di non essere troppo formali :-)
Scelta degli argomenti
Prima di cominciare a tradurre un documento e' buona norma verificare che questo sia disponibile per la traduzione. Infatti, qualcun altro potrebbe essere gia' impegnato nella traduzione di un determinato argomento o questo potrebbe essere gia' stato tradotto. Di norma comunque, i documenti tradotti (o in fase di traduzione) vengono mantenuti quanto piu' aggiornati possibile sul repository CVS. Una lista completa di documenti e dei relativi traduttori e revisionisti e' 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 e' quella con maggiore priorita' 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 verra' creata la directory netbsd 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 1(cvs) in questo modo:
$ cvs -d :pserver:anonymous@netbsdit-docs.cvs.sf.net:/cvsroot/netbsdit-docs -P software/guida-prova
Questa sintassi e' dovuta alla struttura ad albero del repository su cui risiedono i sorgenti, i quali sono distribuiti in modo da rendere quanto piu' semplice possibile la gestione dei file anche agli utenti meno pratici.
Modificare i file
Per il processo di modifica tutto cio' 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) o ancora meglio Vim.
XXX: confesso che l'imparzialita' di quest'ultima frase e' discutibile. Ritengo sia
corretto che si provveda a modificarla (o rimuoverla del tutto) qualora qualcuno
ne avverta la necessita' o piu' semplicemente trovi giusto farlo.
Regole di formattazione
- two spaces for each level of indentation
- lines not longer than 72 characters.
- use separator lines (comments) between sect1/sect2.
Caratteri nazionali
Termini noti
XXX: spostare Traduzioni#Termini in questo paragrafo?
Programmi di utilita'
Installazione
Utilizzo
Pubblicare il lavoro
Per coloro i quali non fossero traduttori e/o revisionisti ufficiale (quindi senza accesso ai repository del progetto NetBSDit-docs) e' consigliato rimediare un account aderendo al progetto come descritto sopra. In alternativa e' possibile contattare direttamente un membro del progetto al fine di delegare a lui il commit della documentazione attualmente tradotta. In questo caso sara' 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 e' 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. E' 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
Cosi' facendo verra' 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 po' di confusione, e' bene seguire poche linee guide al fine di essere quanto piu' efficienti possibili. In particolar modo per i nuovi arrivati e' 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;
- 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;
- 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 documentazione al fine di estendere le guide ufficiali.
