[PLUTO-ildp] Guida a ILDP

[Claudio Cattazzo]

Su "http://www.pluto.linux.it/~claudio/Guida-ILDP/" trovate un documento che
ho scritto e che dovrebbe sostituire lo "Stato del progetto di traduzione
degli HOWTO" scritto da Eugenia, che ormai inizia ad avere i suoi anni (il
documento intendo, non Eugenia :-)).

Ho inserito anche alcuni consigli per una buona traduzione, alcuni dei quali
piuttosto personali, quindi criticabili!

Se va tutto bene diventerebbe un po' il documento centrale del progetto
ILDP, quello da leggere soprattutto se si vuole iniziare a collaborare,
quindi mi aspetto che lo leggiate tutti quanti e che facciate molta critica,
sempre su questa lista ovviamente. Se trovate parti che pensate sarebbe
meglio eliminare, aggiungere o modificare fatelo presente, e` importante.

Per una versione in testo semplice
"http://www.pluto.linux.it/~claudio/Guida-ILDP/Guida-ILDP.txt".

Inoltre, allego il txt del documento, in modo che sia facilmente quotabile
in caso di reply a questo messaggio. Dall'allegato ho tolto le sezioni
relative allo stato delle traduzioni, dato che occuperebbe spazio inutile in
questa mail, il documento completo e` disponibile agli indirizzi indicati
sopra.

-- 
Ciao,
Claudio
-------------- parte successiva --------------

Guida a ILDP

   Questo documento, elaborato grazie al contributo di tutti i
   partecipanti al progetto ILDP, vuole essere una sorta di ILDP HOWTO,
   una guida orientata a chi per la prima volta desidera aggiungersi al
   progetto per collaborare e aiutare la comunità Linux italiana
   traducendo, scrivendo o anche semplicemente leggendo documentazione.
     _________________________________________________________________

   Sommario
   1. Introduzione

        1.1. ILDP e TLDP

   2. Convenzioni utilizzate per la documentazione

        2.1. Formato dei documenti
        2.2. Licenze
        2.3. Linguaggio

   3. Collaborare con ILDP

        3.1. Tradurre un documento
        3.2. Consigli per le traduzioni
        3.3. Glossario
        3.4. Scrivere un documento
        3.5. Il revisore
        3.6. Pagine man

   4. Stato delle traduzioni

        4.1. Howto
        4.2. Mini-Howto
        4.3. Guide di LDP
        4.4. Documentazione non derivante da TLDP

   5. Stato delle redazioni
   6. Contatti
     _________________________________________________________________

Capitolo 1. Introduzione

Questo documento ha la pretesa di fornire alcune indicazioni per chi volesse
iniziare a collaborare con il progetto ILDP per la scrittura, traduzione o
revisione di documentazione inerente a GNU/Linux e Software Libero. Si
propone inoltre di essere un rapporto, il più aggiornato possibile, sullo
stato dei lavori di traduzione dei documenti del Linux Documentation Project
(http://tldp.org).

La versione più recente di questo documento è consultabile via web sul sito
di ILDP (http://ildp.pluto.linux.it), mentre altri formati quali il testo
semplice e il DocBook sono reperibili rispettivamente su INDIRIZZO e
INDIRIZZO.
     _________________________________________________________________

1.1. ILDP e TLDP

ILDP, acronimo di Italian Linux Documentation Project
(http://ildp.pluto.linux.it), nonostante il nome inglese è un progetto tutto
italiano portato avanti da volontari appassionati di GNU/Linux e Software
Libero che collaborano nella loro diffusione tramite la traduzione e la
creazione di documentazione.

Per i documenti da tradurre si fa principalmente riferimento a TLDP (The
Linux Documentation Project, http://tldp.org), fonte di ottima
documentazione su argomenti specifici, nel caso ad esempio di Howto e
Mini-Howto, su argomenti più generali, come le Guide, oppure su determinati
comandi, come le pagine man. Ciò non toglie che ILDP ospiti presso il
proprio sito anche traduzioni di documentazione non proveniente da LDP.
     _________________________________________________________________

Capitolo 2. Convenzioni utilizzate per la documentazione

Per un progetto come ILDP è necessario definire alcune regole che chi scrive
o traduce documenti deve seguire, in maniera da uniformare, almeno sotto
alcuni punti, i lavori che risiedono su ILDP.
     _________________________________________________________________

2.1. Formato dei documenti

Solitamente i documenti vengono tradotti o creati in formati quali SGML
(Standard Generalized Markup Language) oppure il suo derivato XML
(Extensible Markup Language). In particolare, viene preferita una versione
di SGML che utilizza il DTD (Document Type Definition) SGML DocBook
(http://www.docbook.org). Nella creazione di un nuovo documento, la scelta
tra XML e SGML è affidata all'autore, che comunque può ovviamente chiedere
consiglio sulla mailing list di ILDP, mentre nella traduzione di documenti,
il tutto di solito avviene nello stesso formato del documento originale.

Come ILDP, anche il Linux Documentation Project (http://tldp.org) utilizza
in grandissima parte i formati SGML e XML, principalmente per i seguenti
motivi:

     * Da un documento SGML è possibile generare in maniera semplice,
       veloce e soprattutto automatica molti altri formati come HTML,
       testo semplice, PostScript, RTF, ecc...
     * Risulta particolarmente comodo in quanto vengono generati
       automaticamente indici e non ci si deve occupare della
       formattazione del documento come in HTML, non serve quindi
       precisare stili dei paragrafi, caratteristiche dei font, ecc...
     * La qualità tipografica dei documenti ricavati è ottima
     * I documenti da cui si parte con le traduzioni, essendo
       principalmente provenienti da TLDP, sono già in formato SGML o
       XML, quindi in linea di principio non è neppure necessario
       conoscere tali linguaggi, dato che è sufficiente semplicemente
       tradurre mantenendo i tag originali
     * Nel caso si dovesse scrivere un documento da zero sarebbe
       necessario impararsi, anche se a livello minimo, uno dei linguaggi
       specificati, opera non poi così difficile, soprattutto se si ha
       già esperienza con linguaggi come l'HTML. In alternativa si può
       pensare di creare il documento in un formato a propria scelta e
       demandare l'opera di conversione in SGML ad un revisore,
       l'importante è che il documento che giunge al coordinatore per
       l'upload sia in uno dei formati previsti

   Per maggiori informazioni sull'SGML e sulla conversione da SGML a vari
   formati esistono numerosi documenti facilmente reperibili sulla rete,
   come ad esempio il DocBook Install mini-HOWTO e il
   DocBook-OpenJade-SGML-XML-HOWTO, al momento disponibili unicamente in
   lingua inglese, e gli Appunti di informatica libera
   (http://ildp.pluto.linux.it/AppuntiLinux/).
     _________________________________________________________________

2.2. Licenze

Data la natura del progetto ILDP, si hanno particolarmente a cuore le
ideologie del Software Libero e più in generale di libertà informatica. Per
questo motivo tutta la documentazione presente su ILDP deve essere
distribuita sotto i termini di licenze libere, ad esempio GPL (General
Public License) o FDL (Free Documentation License). Per maggiori
informazioni su queste licenze si veda il sito del progetto GNU,
all'indirizzo http://www.gnu.org/licenses/licenses.html.

Questo vale in particolare per i documenti creati direttamente in italiano,
dato che il progetto LDP prevede già di suo la pubblicazione di
documentazione libera.
     _________________________________________________________________

2.3. Linguaggio

Per la forma di scrittura, è stato scelto da ILDP, oltre che da altri
progetti come TP (http://www.linux.it/tp/), di utilizzare la forma
impersonale quando ci si rivolge al lettore; quindi, per fare un esempio, è
preferibile utilizzare "si veda" o in alternativa "vedere" piuttosto di
"vedete" o "vedi". Non è tuttavia una regola così rigida, soprattutto per
documenti come Howto e Mini-Howto. Si può utilizzare la forma impersonale o
la seconda persona plurale a seconda dei casi e del gusto del
traduttore/redattore. Inoltre, il linguaggio con cui si scrive e si traduce
non deve essere elevato e ricercato, deve tuttavia essere obbligatoriamente
preciso.

Si porga anche attenzione all'utilizzo di termini tecnici, che oralmente
possono derivare dall'italianizzazione di termini inglesi ma che per
documenti scritti necessitano di particolari forme; ad esempio il verbo "to
log in" potrebbe essere tradotto con "loggarsi", ma risulta più elegante
utilizzare la forma "fare il login", o simili. Nel caso di traduzioni, è
necessario trovare un buon compromesso tra fedeltà al testo inglese e
correttezza italiana.

Altri preziosi consigli per una buona traduzione possono essere trovati nel
glossario di TP, reperibile all'indirizzo
ftp://ftp.linux.it/pub/People/md/glossario.tgz.
     _________________________________________________________________

Capitolo 3. Collaborare con ILDP

Per collaborare con il progetto ILDP ci si iscriva innanzitutto alla mailing
list pluto-ildp (si veda Capitolo 6) in modo da illustrare i documenti, sia
da tradurre che da creare, su cui si intende lavorare.

Il presente capitolo definisce delle specifiche e alcuni consigli per i
traduttori o redattori di documentazione, da aggiungersi alle informazioni
già presentate nel capitolo precedente (Capitolo 2).
     _________________________________________________________________

3.1. Tradurre un documento

La sequenza ideale per tradurre un documento è la seguente: iscriversi alla
mailing list pluto-ildp e chiedere se c'è la necessità di tradurre qualche
documento in particolare, magari descrivendo i propri interessi (ad esempio
reti, sicurezza, programmazione, ecc...). Entro breve dovrebbe pervenire una
risposta; se viene proposto di tradurre qualche documento di proprio
interesse si colga al volo l'occasione, in caso contrario si cerchi sul sito
del Linux Documentation Project (http://tldp.org) un documento non tradotto
in italiano (si veda Capitolo 4). Nel caso di Howto e Mini-Howto, i
documenti sorgenti si possono prelevare dal CVS di LDP, all'indirizzo
http://cvsview.tldp.org/index.cgi/LDP/howto/, mentre le Guide sono
disponibili sempre sul CVS all'indirizzo
http://cvsview.tldp.org/index.cgi/LDP/guide/.

A questo punto, o appena finita la traduzione, verrà affidato al traduttore
almeno un revisore, incaricato di controllare il documento tradotto e di
suggerire al traduttore delle possibili correzioni.

Una volta completata la traduzione la si può inviare al proprio revisore,
che dopo averla controllata la fa pervenire al coordinatore, il quale
converte il documento nei vari formati di utilizzo più comune (tipicamente
HTML e testo semplice) e ne effettua l'upload sul sito di ILDP, aggiornando
anche lo Stato delle Traduzioni (si veda Capitolo 4).

Naturalmente, per uno stesso documento ci possono essere anche più
traduttori e più revisori, soprattutto per documenti di un certo volume. In
questi casi si può decidere di creare un piccolo gruppo di lavoro per
dividere il carico su più persone.
     _________________________________________________________________

3.2. Consigli per le traduzioni

Oltre ai consigli già forniti in precedenza in questo stesso documento
(Capitolo 2), informazioni relative esclusivamente alle opere di traduzione,
quindi non inerenti alla creazione di nuovi documenti, sono ad esempio
quelle riguardanti le licenze.

Ogni documento ha una licenza che ne permette la distribuzione e la copia.
Di licenze ne esitono diverse ma quasi tutte, nel caso di licenze libere,
hanno in comune il fatto che del documento se ne può fare sostanzialmente
quello che si desidera a patto di non modificarne la licenza ed
eventualmente avvertire l'autore di quello che si intende fare. Quindi, per
non violare la licenza originale e affinché questa rimanga valida, le note
di copyright devono essere mantenute in lingua originale,a meno che non
siano semplicemente un riferimento ad una particolare licenza. Quindi se si
vuole si può tradurre la sezione relativa alla licenza, avendo però
l'accortezza di mantenere anche la versione originale all'interno del
documento. A meno di casi particolari la Liberatoria (Disclaimer) può essere
tranquillamente tradotta.

Un ulteriore consiglio è quello di conservare le proprie copie dei file
SGML/XML, sia la versione tradotta che quella originale, in modo da scoprire
in maniera immediata, in caso di aggiornamenti nel documento originale, cosa
è stato cambiato, così da poter aggiornare la versione italiana in breve
tempo.

Nella sezione precedente è stato detto che il documento tradotto avrà lo
stesso codice SGML del documento originale. In realtà è necessario
effettuare una piccola modifica ai tag <book> e <article>, presenti
all'inizio del documento. Si noti che un documento contiene un tag o
l'altro, ma non entrambi. I tag precedenti diventano rispettivamente <book
lang="it"> e <article lang="it">.

È infine consigliato di inserire tra i tag <abstract> del documento tradotto
una frase che indichi nome e email del traduttore.
     _________________________________________________________________

3.3. Glossario

È indispensabile, o quasi, procurarsi una copia del glossario di TP
(http://www.linux.it/tp/), che contiene regole per una buona traduzione ed
una lista di termini e concetti comuni nei testi inglesi tecnici, quali
possono considerarsi gli Howto, la cui traduzione è già stata a lungo
discussa ed ufficialmente decisa. È possibile trovare la versione più
recente su ftp://ftp.linux.it/pub/People/md/glossario.tgz.

Il progetto TP mette a disposizione anche una mailing list per le
discussioni su come tradurre termini o concetti; per iscriversi alla lista
<tp a lists.linux.it> si veda la pagina relativa a TP.
     _________________________________________________________________

3.4. Scrivere un documento

Il progetto ILDP non si occupa esclusivamente della traduzione di
documentazione, ma ospita anche documentazione scritta direttamente in
italiano.

ILDP può in generale ospitare qualsiasi documento, l'importante è che questo
abbia alcuni requisiti fondamentali, in particolare deve essere distribuito
sotto una licenza libera e deve trattare argomenti inerenti a GNU/Linux e al
Software Libero.
     _________________________________________________________________

3.5. Il revisore

La figura del revisore ha essenzialmente il compito di controllare un
documento creato o tradotto e in particolare ha le seguenti funzioni:

     * Controllare che la traduzione di un documento sia corretta
     * Controllare che la forma italiana del documento sia corretta. Come
       già detto, nelle traduzioni è necessario trovare un buon
       compromesso tra fedeltà al testo originale e correttezza e
       fluidità delle frasi in italiano; capita a volte che alcune
       traduzioni troppo letterali lascino un po' a desiderare in quanto
       a italiano
     * Nel caso il traduttore/redattore entri in panico appena vede
       qualche tag, il revisore ha il compito di convertire in uno dei
       formati previsti dal progetto ILDP (tipicamente SGML o XML) il
       file inviatogli. Ovviamente in questo caso è necessario mettersi
       d'accordo preventivamente tra traduttore/redattore e revisore.
       Tuttavia questo procedimento è sconsigliato, soprattutto nel caso
       di traduzioni; è preferibile lavorare direttamente sul documento
       originale, traducendo tra i tag, che vengono quindi lasciati
       inalterati
     * In generale, controllare che i documenti soddisfino requisiti come
       quelli elencati in precedenza su questo documento (Capitolo 2)

   Anche una persona che non conosce l'inglese può quindi essere
   estremamente utile, può controllare la correttezza in italiano,
   dilettarsi con l'SGML, ecc...
     _________________________________________________________________

3.6. Pagine man

Oltre alle traduzioni di documenti come Howto, Mini-Howto, Guide e FAQ,
esistono le versioni tradotte anche delle pagine di manuale (man), contenute
nel pacchetto manpages-it, disponibile per qualsiasi sistema Linux.

La sezione di ILDP relativa a questo progetto si può trovare su
http://ildp.pluto.linux.it/man/. Per collaborare con il progetto di
traduzione delle pagine man si scriva alla mailing list pluto-ildp oppure a
Fabio Teatini, <teafab a pluto.linux.it>.
     _________________________________________________________________

Capitolo 4. Stato delle traduzioni

In queste sezioni sono elencati tutti i documenti tradotti che risiedono sul
sito di ILDP. Per ogni documento è presente uno schema simile a quello
seguente:

Nome Documento

     Coordinatore: Nome_Coordinatore <Email_Coordinatore>
     Traduttore: Nome_Traduttore <Email_Traduttore>
     Revisore: Nome_Revisore <Email_Revisore>
     Versione: Versione

Il campo Coordinatore è presente nel caso in cui una traduzione sia molto
corposa e per la quale venga organizzato un gruppo di lavoro. In questo caso
se all'interno del gruppo è presente una persona che coordina il tutto viene
indicata.

Il campo Revisore è tralasciato per traduzioni di qualche tempo fa.

Il campo Versione contiene la versione del documento originale in formati
che possono variare, ad esempio data o valore numerico.

Si noti che alcune traduzioni risalgono in qualche caso anche a vari anni
fa, quindi non è detto che gli indirizzi di posta elettronica indicati siano
validi.
     _________________________________________________________________

4.1. Howto

[tagliato]

     _________________________________________________________________

4.2. Mini-Howto

[tagliato]

     _________________________________________________________________

4.3. Guide di LDP

[tagliato]

     _________________________________________________________________

4.4. Documentazione non derivante da TLDP

È in corso la traduzione del Vim User Manual.

[tagliato]

     _________________________________________________________________

Capitolo 5. Stato delle redazioni

In questa sezione sono elencati tutti i documenti scritti direttamente in
italiano ospitati presso ILDP. Anche qui vale lo stesso schema utilizzato
nelle sezioni relative allo Stato delle traduzioni (Capitolo 4).
     _________________________________________________________________

Capitolo 6. Contatti

Per contattare i collaboratori del progetto ILDP ci si può iscrivere alla
mailing list pluto-ildp, tramite la form online disponibile alla pagina
http://lists.pluto.linux.it/mailman/listinfo/pluto-ildp oppure inviando
un'email contenente nel corpo del messaggio la sola parola subscribe a
<pluto-ildp-request a lists.pluto.linux.it>. Una volta completata
l'iscrizione, per inviare un messaggio a tutti gli iscritti alla mailing
list è sufficiente scrivere a <pluto-ildp a lists.pluto.linux.it>.

Tale lista va utilizzata per discutere tutte le problematiche, proposte e
quant'altro riguardi la documentazione su Linux in italiano, non solo per le
traduzioni quindi. Si noti che non sono pertinenti a questa lista le
discussioni su come tradurre un termine o un concetto: per tali discussioni
esiste la mailing list di TP, <tp a lists.linux.it>. Per maggiori informazioni
si consulti la pagina relativa al progetto TP, all'indirizzo
http://www.linux.it/tp/.

Per qualsiasi problema, informazione, oppure semplicemente per contattare
direttamente il coordinatore del progetto, si scriva a Claudio Cattazzo,
<claudio a pluto.linux.it>.

Se si trovano errori in questa guida o se si hanno dei consigli per
migliorarla si scriva alla mailing list o al coordinatore.