Provided by: po4a_0.73-2ubuntu1_all bug

NOME

       Locale::Po4a::Man - converte pagine di manuale da/a file PO

DESCRIZIONE

       L'obiettivo del progetto po4a (PO per tutto) è di facilitare le traduzioni (e cosa più
       interessante, la manutenzione delle traduzioni) usando gli strumenti associati a gettext
       in aree inaspettate come la documentazione.

       Locale::Po4a::Man è un modulo che aiuta la traduzione in altre lingue della documentazione
       in formato nroff (il linguaggio delle pagine di manuale).

TRADURRE CON PO4A::MAN

       Questo modulo prova fortemente a facilitare la vita ai traduttori. Per far ciò, il testo
       presentato ai traduttori non è una fotocopia del testo trovato nella pagina man. Infatti,
       le parti più grezze del formato nroff vengono nascoste, in modo che i traduttori non
       possano rovinarle.

   A capo del testo
       I paragrafi non indentati vengono formattati automaticamente per il traduttore.  Ciò può
       portare ad alcune differenze minori nel risultato generato, dato che le regole del portare
       a capo usate da groff non sono molto chiare. Per esempio, due spazi dopo una parentesi
       alle volte vengono conservati.

       Comunque, la differenza riguarderà solamente la posizione degli spazi extra nei paragrafi
       riformattati, e dovrebbe valere la pena.

   Indicazione font
       Il primo cambiamento riguarda le specifiche del cambiamento del font.  In nroff, ci sono
       diversi modi per specificare se una data parola dovrebbe essere scritta in minuscolo,
       grassetto o corsivo. Nel testo da tradurre, c'è un unico modo, preso a prestito dal
       formato POD (Perl online documentation):

       I<testo> -- testo in corsivo
           equivalente a \fItesto\fP o ".I testo"

       B<testo> -- testo in grassetto
           equivalente a \fBtesto\fP or ".B testo"

       R<testo> -- testo con grazie
           equivalente a \fRtesto\fP

       CW<testo> -- testo a larghezza costante
           equivalente a \f(CWtesto\fP or ".CW testo"

       Nota: il CW face non è disponibile per tutti i dispositivi groff. Se ne sconsiglia l'uso.
       Viene fornito solo per comodità dell'utente.

   Transliterazione automatica caratteri
       Po4a automaticamente translitera alcuni caratteri per facilitarne la traduzione o la
       revisione della traduzione.  Ecco l'elenco delle transliterazioni:

       trattino
           Trattini (-) e segni meno (\-) nelle pagine man vengono transliterati come semplici
           lineette (-) nei file PO.  Poi tutte le lineette sono transliterate in segni meno di
           roff (\-) quando la traduzione viene inserita nel documento in uscita.

           I traduttori possono forzare un trattino usando il glifo roff '\[hy]' nelle loro
           traduzioni.

       spazi non interrompenti
           I traduttori possono usare spazi non interrompenti nelle loro traduzioni. Questi spazi
           non interrompenti (0xA0 in latin1) verranno transliterati in uno spazio non
           interrompente roff ('\ ').

       transliterazione apici
           `` e '' vengono transliterati rispettivamente in \*(lq e \*(rq.

           Per evitare queste transliterazioni, i traduttori possono inserire un carattere nroff
           di larghezza zero (cioè, usando rispettivamente `\&` o '\&').

   Mettere '<' e '>' nelle traduzioni
       Siccome questi caratteri vengono usati per delimitare parti sottoposte a modifiche del
       font, non si possono usare direttamente. In alternativa si consiglia di usare E<lt> e
       E<gt> (ancora una volta, come nei POD).

OPZIONI ACCETTATE DA QUESTO MODULO

       Queste sono le opzioni speciali per questo modulo:

       debug
           Attiva il debug per alcuni meccanismi interni di questo modulo.  Usare i sorgenti per
           vedere quali parti possono essere controllate.

       verbose
           Rende il programma più prolisso.

       groff_code
           Questa opzione controlla il comportamento del modulo quando questo incontra una
           sezione un .de, .ie o .if . Può prendere i seguenti valori:

           fail
               È il valore predefinito.  Il modulo fallirà quando incontrerà una sezione .de, .ie
               o .if .

           verbatim
               Indica che le sezioni .de, .ie o .if devono venir copiate come sono dall'originale
               nel documento tradotto.

           translate
               Indica che le sezioni .de, .ie o .if verranno proposte per la traduzione. Si
               dovrebbe usare questa opzione solo se una stringa traducibile fosse presente in
               una di dette sezioni. Altrimenti, sarebbe preferibile verbatim.

       generated
           Questa opzione specifica che il file è un file generato, e che quindi po4a non
           dovrebbe cercare di rilevare se le pagine man siano state generate da un altro
           formato. Questa opzione è necessaria per usare po4a su pagine man generate. Si noti
           che tradurre pagine generate invece di quelle sorgenti è spesso più fragile (N.d.T: è
           più facile fare errori), e quindi una cattiva idea.

       mdoc
           Questa opzione è utile solo per le pagine mdoc.

           Seleziona un supporto più stringente del formato mdoc indicando a po4a di non tradurre
           la sezione 'NAME'. Le pagine mdoc la cui sezione 'NAME' è tradotta non genereranno
           alcuna intestazione o piè di pagina.

           Secondo la pagina groff_mdoc, le sezioni NOME, SINTASSI e DESCRIZIONE sono
           obbligatorie.  Non sembrano esserci problemi conosciuti nel tradurre le sezioni
           SINTASSI o DESCRIZIONE, ma si può specificare queste sezioni anche in questo modo:
            -o mdoc=NOME,SINTASSI,DESCRIZIONE

           Questo problema di mdoc può essere risolto anche con un addendum come questo:
            PO4A-HEADER:mode=before;position=^.Dd
            .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"

       Le opzioni seguenti specificano il comportamento di una macro personalizzata (definita con
       una richiesta .de), o di una macro classica non supportata da po4a.  Prendono come
       argomento un elenco separato da virgole di macro.  Per esempio:

        -o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX

       Nota: se una macro macro non è supportata da po4a e si ritiene che sia una macro standard
       roff, sarebbe desiderabile comunicarlo al team di sviluppo di po4a (N.d.T. per
       un'eventuale inclusione in una prossima versione di po4a).

       untranslated
           untranslated indica che questa macro (ed i suoi argomenti) non deve essere tradotta.

       noarg
           noarg è come untranslated, eccetto per il fatto che po4a verificherà che non venga
           aggiunto nessun argomento a questa macro.

       translate_joined
           translate_joined indica che po4a deve proporre di tradurre gli argomenti della macro.

       translate_each
           Anche con translate_each, gli argomenti verranno proposti per la traduzione, ma ognuno
           verrà tradotto separatamente.

       no_wrap
           Questa opzione prende come argomento un elenco di coppie separate da virgole
           begin:end, dove begin e end sono comandi che delimitano rispettivamente l'inizio e la
           fine di una sezione che non dovrebbe essere riformattata.

           Nota: non viene effettuata nessuna prova per assicurare che il comando end corrisponda
           al suo comando begin; qualunque comando di fine interrompe la modalità no_wrap.  Se si
           ha una macro begin (o rispettivamente end) che non ha un end (o rispettivamente
           begin), si può specificare un end esistente (come fi) o begin (come nf) come
           controparte.  Queste macro (ed i loro argomenti) non verranno tradotte.

       inline
           Questa opzione specifica un elenco separato da virgole di macro che non devono
           spezzare il paragrafo corrente. La stringa da tradurre conterrà perciò foo <.bar baz
           qux> quux, dove bar è il comando che dovrebbe essere messo sulla stessa riga, e baz
           qux i suoi argomenti.

       unknown_macros
           Questa opzione indica come po4a dovrebbe comportarsi quando trova una macro
           sconosciuta.  Per impostazione predefinita, po4a fallisce con un avvertimento.  Può
           prendere i seguenti valori: failed (il valore predefinito), untranslated, noarg,
           translate_joined, o translate_each (vedere sopra per una spiegazione di questi
           valori).

CREAZIONE DI PAGINE COMPATIBILI MAN CON PO4A::MAN

       Questo modulo è ancora molto limitato, e lo sarà sempre, perché non è un vero interprete
       nroff. Sarebbe possibile fare un vero interprete nroff, per consentire agli autori di
       utilizzare tutte le macro esistenti, o anche definirne di nuove nelle loro pagine, ma non
       abbiamo voluto. Sarebbe stato troppo difficile, e pensavamo che non fosse necessario.
       Pensiamo che se gli autori delle manpage vogliono vedere le loro produzioni tradotte,
       potrebbero doversi adattare per facilitare il lavoro dei traduttori.

       Perciò, il parser man implementato in po4a ha alcune limitazioni note, che non abbiamo
       intenzione di correggere, e che potranno presentare dei problemi che sarà necessario
       evitare se si vuole che i traduttori si prendano cura della propria documentazione.

   Non programmare in nroff
       nroff è un linguaggio di programmazione completo, con definizione di macro, condizionali e
       così via. Poiché questo parser non è un interprete nroff completo, non funzionerà sulle
       pagine che utilizzano queste funzionalità (ci sono circa 200 di queste pagine sul mio
       sistema).

   Usare l'insieme di macro di base
       Ci sono ancora alcune macro che non sono supportate da po4a::man. Questo solo perché non
       siamo riusciti a trovare nessuna documentazione su di esse. Ecco l'elenco delle macro non
       supportate utilizzate sul mio sistema. Si noti che questo elenco non è esaustivo poiché il
       programma non riesce sulla prima macro non supportata incontrata. Se potete fornire
       informazioni su alcune di queste macro, aggiungeremo volentieri il supporto per esse. A
       causa di queste macro, circa 250 pagine del mio sistema sono inaccessibili a po4a::man.

        ..               ."              .AT             .b              .bank
        .BE              ..br            .Bu             .BUGS           .BY
        .ce              .dbmmanage      .do                             .En
        .EP              .EX             .Fi             .hw             .i
        .Id              .l              .LO             .mf
        .N               .na             .NF             .nh             .nl
        .Nm              .ns             .NXR            .OPTIONS        .PB
        .pp              .PR             .PRE            .PU             .REq
        .RH              .rn             .S<             .sh             .SI
        .splitfont       .Sx             .T              .TF             .The
        .TT              .UC             .ul             .Vb             .zZ

   Nascondere il testo a po4a
       A volte, l'autore sa che alcune parti non vanno tradotte e non dovrebbero essere estratte
       da po4a. Ad esempio, un'opzione potrebbe accettare un argomento other e other potrebbe
       apparire anche come ultimo elemento di un elenco. Nel primo caso, other non dovrebbe
       essere traducibile. E nel secondo caso, other dovrebbe essere tradotto.

       In tal caso, l'autore può evitare che po4a estragga alcune stringhe, utilizzando alcuni
       costrutti groff speciali:

        .if !'po4a'hide' .B other

       (ciò richiederà l'opzione -o groff_code=verbatim)

       Si può anche definire una nuova macro per automatizzare l'operazione:
        .de IR_untranslated
        .    IR \\$@
        ..

        .IR_untranslated \-q ", " \-\-quiet

       (questo richiederà le opzioni -o groff_code=verbatim e -o untranslated=IR_untranslated;
       con questo costrutto, il condizionale .if !'po4a'hide' non è strettamente necessario dato
       che po4a non analizzerà l'interno della definizione della macro)

       o usando un'alias:
        .als IR_untranslated IR

        .IR_untranslated \-q ", " \-\-quiet

       Ciò richiederà l'opzione -o untranslated=als,IR_untranslated.

   Conclusione
       Per riassumere, fare le cose semplicemente non cercando trucchi complessi nella creazione
       delle pagine man. Molte cose possibili in nroff non sono supportate da questo parser. Ad
       esempio, non si provi a pasticciare con \c per interrompere l'elaborazione del testo (come
       fanno 40 pagine sul mio sistema). In alternativa, assicurarsi di inserire gli argomenti
       della macro sulla stessa unica riga della macro. È valido in nroff, ma complicherebbe
       troppo la gestione del parser.

       Naturalmente, un'altra possibilità è usare un altro formato, più facile da tradurre (come
       il formato POD usando po4a::pod, o uno della famiglia XML come SGML), ma grazie a
       po4a::man, ciò non è comunque più necessario. Detto questo, se il formato sorgente della
       documentazione è POD o XML, potrebbe essere conveniente tradurre il formato sorgente e non
       quello generato. Nella maggior parte dei casi, po4a::man rileverà le pagine generate ed
       emetterà un avviso. Si rifiuterà persino di elaborare le pagine generate dal POD, perché
       quelle pagine sono perfettamente gestite da po4a::pod e perché la loro controparte nroff
       definisce molte nuove macro per le quali non si è voluto darne supporto. Per esempio,
       sulla macchina di uno degli autori, 1432 delle 4323 pagine presenti vengono generate da
       file POD e sono ignorate da po4a::man.

       Nella maggior parte dei casi, po4a::man rileverà il problema e si rifiuterà di elaborare
       la pagina, inviando un messaggio conforme. In alcuni rari casi, il programma verrà
       completato senza preavviso, ma l'output sarà comunque errato. Tali casi sono chiamati
       "bug" ;) Se incontra un caso del genere, sarebbe gradita la segnalazione, insieme a una
       correzione se possibile...

STATO DI QUESTO MODULO

       Questo modulo può essere usato per la maggior parte delle pagine man esistenti.

       Alcuni test vengono effettuati con regolarità su macchine Linux:

       •   un terzo delle pagine vengono rifiutate perché sono state generate da un altro formato
           supportato da po4a (per es. POD o SGML).

       •   il 10% delle pagine rimanenti vengono rifiutate con un errore (perché per es. una
           macro groff non è supportata).

       •   Poi, meno dell'1% delle pagine vengono accettate da po4a silenziosamente (N.d.T.
           ovvero senza segnalazioni), ma con problemi significativi (cioè parole mancanti, o
           nuove parole inserite)

       •   Le altre pagine vengono solitamente gestite senza differenze più rilevanti delle
           differenze di spaziatura o dell'andare a capo delle righe (problemi relativi ai font
           in meno del 10% delle pagine elaborate).

VEDERE ANCHE

       Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

AUTORI

        Denis Barbier <barbier@linuxfr.org>
        Nicolas François <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

TRADUZIONE

        Danilo Piazzalunga <danilopiazza@libero.it>
        Marco Ciampa <ciampix@posteo.net>

COPYRIGHT E LICENZA

       Copyright © 2002-2008 by SPI, inc.

       Questo programma è software libero; è lecito ridistribuirlo o modificarlo secondo i
       termini della licenza GPL v2.0 o successive (vedere il file COPYING).