Provided by: po4a_0.73-2ubuntu1_all bug

NOME

       Locale::Po4a::TeX - converte documenti TeX e derivati 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::TeX è un modulo che aiuta la traduzione in altre lingue della documentazione
       in formato TeX. Può anche essere usato come base per scrivere moduli per documenti basati
       su TeX.

       Gli utenti dovrebbero probabilmente usare il modulo LaTeX, che eredita dal modulo TeX e
       contiene le definizioni di tipici comandi LaTeX.

TRADURRE CON PO4A::TEX

       Questo modulo può essere usato direttamente per gestire generici documenti TeX. Dividerà
       il documento in blocchi più piccoli (paragrafi, blocchi verbatim o anche più piccoli come
       titoli o indici).

       Ci sono alcune opzioni (descritte nella sezione successiva) che possono personalizzare
       questo comportamento.  Se questo non dovesse adattarsi sufficientemente al formato del
       proprio documento si incoraggia a scriverne uno per il proprio modulo derivandolo da
       questo, per descrivere i dettagli del proprio formato. Consultare la prossima sezione
       SCRIVERE MODULI DERIVATI più sotto, per la descrizione del processo.

       Questo modulo può essere personalizzato anche da righe che comincino con "% po4a:" nel
       file TeX. Queste personalizzazioni sono descritte nella sezione PERSONALIZZAZIONE INLINE.

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.

       no_wrap
           Elenco separato da virgole di ambienti che non dovrebbero essere mandati a capo.

           Si noti che c'è una differenza tra ambienti verbatim e no_wrap. Non c'è analisi
           comandi e commenti nei blocchi verbatim.

           Se questo ambiente non fosse già registrato, po4a considererà che questo ambiente non
           usi nessun parametro.

       exclude_include
           Elenco di file separato da simboli di due punti che non dovrebbero essere inclusi da
           \input e \include.

       definitions
           Il nome del file contenente le definizioni per po4a, come definito nella sezione
           PERSONALIZZAZIONE INLINE.  Si può usare questa opzione se non è possibile mettere le
           definizioni nel documento che si sta traducendo.

       verbatim
           Elenco separato da virgole di ambienti che devono essere lasciati inalterati.

           Se questo ambiente non fosse già registrato, po4a considererà che questo ambiente non
           usi nessun parametro.

       L'uso di queste opzioni permette di scavalcare il comportamento predefinito dei comandi
       definiti.

PERSONALIZZAZIONE INLINE

       Il modulo TeX può essere personalizzato con righe che cominciano con % po4a:.  Queste
       righe vengono interpretate come comandi passati al parser. I comandi seguenti sono
       riconosciuti:

       % po4a: command comando1 alias comando2
           Indica che gli argomenti del comando comando1 devono essere trattati come argomenti
           del comando comando2.

       % po4a: command comando1 parametri
           Questo descrivere in dettaglio i parametri del comando comando1.  Questa informazione
           verrà usata per controllare il numero di argomenti ed i loro tipi.

           Si può precedere il comando comando1 da

           un asterisco (*)
               po4a estrarrà questo comando dai paragrafi (se è posizionato all'inizio o alla
               fine del paragrafo).  I traduttori dovranno allora tradurre i parametri marcati
               come traducibili.

           un segno più (+)
               Come per un asterisco, il comando verrà estratto se appare ad un'estremità di un
               blocco, ma i parametri non saranno tradotti separatamente.  Il traduttore dovrà
               tradurre il comando concatenato a tutti i suoi parametri. Ciò mantiene più
               contesto, ed è utile per comandi con piccole parole nei parametri, che possono
               avere significati (e traduzioni) multipli.

               Nota: in questo caso non è necessario specificare quali parametri sono
               traducibili, ma po4a deve sapere il tipo e numero di parametri.

           un segno meno (-)
               In questo caso, il comando non sarà estratto da nessun blocco. Ma se apparirà da
               solo in un blocco, allora solo i parametri marcati come traducibili saranno
               presentati al traduttore.  Ciò è utile per i comandi sui font.  Questi comandi
               generalmente non dovrebbero essere separati dai loro paragrafi (per mantenere il
               contesto), ma non c'è ragione di infastidire il traduttore con essi se un'intera
               stringa è racchiusa in un tale comando.

           L'argomento parametri è un insieme di [] (per indicare un argomento opzionale) o {}
           (per indicare un argomento obbligatorio). Si può piazzare un carattere di
           sottolineatura (_) tra queste parentesi per indicare che il parametro deve essere
           tradotto. Per esempio:
            % po4a: command *capitolo [_]{_}

           Questo indica che il comando del capitolo ha due parametri: uno opzionale (titolo
           corto) e uno obbligatorio, che devono entrambi essere tradotti.  Se si vuole
           specificare che il comando href abbia due parametri obbligatori, che non si vuole
           tradurre l'URL (primo parametro), e che non si vuole che questo comando sia separato
           dal suo paragrafo (il che permette al traduttore di spostare il collegamento nel
           testo), si può usare:
            % po4a: command -href {}{_}

           In questo caso, l'informazione indicante quali argomenti devono essere tradotti viene
           usata solo se un paragrafo è composto solo da questo comando href.

       % po4a: environment env parametri
           Questo definisce i parametri accettati dall'ambiente env e specifica quelli che vanno
           tradotti.  Questa informazione viene in seguito usata per controllare il numero di
           argomenti del comando \begin.  La sintassi dell'argomento parameters è la stessa
           descritta per gli altri comandi.  Il primo parametro del comando \begin è il nome
           dell'ambiente.  Questo parametro non deve essere specificato nell'elenco dei
           parametri.  Ecco alcuni esempi:
            % po4a: environment multicols {}
            % po4a: environment equation

           Come per i comandi, env può essere preceduto da un più (+) per indicare che il comando
           \begin deve essere tradotto con tutti i suoi argomenti.

       % po4a: separator env "regex"
           Indica che un ambiente dovrebbe essere diviso secondo la data espressione regolare.

           L'espressione regolare è delimitata da virgolette.  Non si dovrebbe creare nessun
           riferimento all'indietro. Si dovrebbe usare (?:) se serve un gruppo. Potrebbero
           servire anche qualche carattere di escape.

           Ad esempio, il modulo LaTeX utilizza l'espressione regolare "(?:&|\\\\)" per tradurre
           separatamente ogni cella di una tabella (le righe sono separate da '\\' e le celle da
           '&').

           La nozione di ambiente viene estesa al tipo visualizzato nel file PO. Ciò può essere
           usato per dividere su "\\\\" nel primo argomento obbligatorio del comando title. In
           questo caso, l'ambiente è title{#1}.

       % po4a: verbatim environment env
           Indica che env è un ambiente verbatim.  Commenti e comandi verranno ignorati in questo
           ambiente.

           Se questo ambiente non fosse già registrato, po4a considererà che questo ambiente non
           usi nessun parametro.

SCRIVERE MODULI DERIVATI

       pre_trans
       post_trans
       add_comment
           Aggiunge una stringa come commento da aggiungere accanto al prossimo elemento
           tradotto. Utile principalmente per il modulo texinfo, visto che in questo modo i
           commenti possono essere gestiti automaticamente in TeX.

       translate
           Wrapper attorno alla traduzione del Transtractor, con filtri pre- e post-elaborazione.

           I commenti di un paragrafo vengono inseriti come commenti PO per la prima stringa
           tradotta di questo paragrafo.

       get_leading_command($buffer)
           Questa funzione restituisce:

           Un nome comando
               Se non si trova il comando all'inizio del buffer dato, questa stringa sarà vuota.
               Vengono tenuti in considerazione solo comandi che possono essere separati.  L'hash
               %separated_command contiene l'elenco di questi comandi.

           Una variante
               Indica se viene utilizzata una variante. Ad esempio, è possibile aggiungere un
               asterisco (*) alla fine del comando delle sezioni per specificare che non devono
               essere numerate. In questo caso, questo campo conterrà "*". Se non ci sono
               varianti, il campo è una stringa vuota.

           Un'array di tuple (tipo di argomento, argomento)
               Il tipo di argomento può essere '{' (per argomenti obbligatori) o '[' (per
               argomenti facoltativi).

           Il buffer rimanente
               Il resto del buffer dopo la rimozione di questo comando principale e dei suoi
               argomenti. Se non viene trovato alcun comando, il buffer originale non viene
               toccato e restituito in questo campo.

       get_trailing_command($buffer)
           Come get_leading_command, ma per comandi alla fine di un buffer.

       translate_buffer
           Tradurre ricorsivamente un buffer separando i comandi iniziali e finali (quelli che
           dovrebbero essere tradotti separatamente) dal buffer.

           Se viene definita una funzione in %translate_buffer_env per l'ambiente corrente,
           questa funzione verrà utilizzata per tradurre il buffer invece di translate_buffer().

       read
           Fa l'overload della funzione read() di Transtractor.

       read_file
           Legge ricorsivamente un file, aggiungendo i file inclusi che non siano elencati
           nell'array @exclude_include. I file inclusi vengono cercati usando il comando
           kpsewhich dalla libreria Kpathsea.

           Fatta eccezione per la parte di inclusione del file, è un taglia e incolla della
           funzione read di Transtractor.

       parse_definition_file
           Subroutine per l'analisi di un file con direttive po4a (definizioni per nuovi
           comandi).

       parse_definition_line
           Elabora una riga di definizione nella forma "% po4a: ".

           Consultare la sezione PERSONALIZZAZIONE INLINE per ulteriori dettagli.

       is_closed
       parse
       docheader

FUNZIONI INTERNE usate per scrivere parser derivati

       Comando e funzioni ambiente prendono i seguenti argomenti (oltre all'oggetto $self):

       Un nome comando
       Una variante
       Un array di tuple (tipo, argomento)
       L'ambiente corrente

       I primi 3 argomenti vengono estratti da get_leading_command o get_trailing_command.

       Comando e funzioni ambiente restituiscono la traduzione del comando con i suoi argomenti e
       un nuovo ambiente.

       Le funzioni ambiente vengono chiamate quando viene trovato un comando \begin . Vengono
       chiamate con il comando \begin ed i suoi argomenti.

       Il modulo TeX propone solo una funzione comando e una funzione ambiente: generic_command e
       generic_environment.

       generic_command usa le informazioni specificate by register_generic_command o aggiungendo
       una definizione al file TeX:
        % po4a: command comando1 parametri

       generic_environment usa le informazioni specificate da register_generic_environment o
       aggiungendo una definizione al file TeX:
        % po4a: environment ambiente parametri

       Entrambe le funzioni tradurranno solo i parametri che sono stati specificati come
       traducibili (con un '_'). generic_environment aggiungerà il nome dell'ambiente allo stack
       dell'ambiente e generic_command aggiungerà il nome del comando seguito da un
       identificatore del parametro (come {#7} o [#2]).

STATO DI QUESTO MODULO

       Questo modulo necessita di più controlli.

       È stato testato su un libro e con la documentazione Python.

ELENCO DEI DAFARE

       Rilevamento automatico di nuovi comandi
           Il modulo TeX potrebbe analizzare gli argomenti del nuovo comando e provare a
           indovinare il numero di argomenti, il loro tipo e se devono essere tradotti o meno.

       Traduzione del separatore d'ambiente
           Quando \item è usato come separatore d'ambiente, l'argomento item è allegato alla
           stringa seguente.

       Alcuni comandi dovrebbero essere aggiunti alla pila dell'ambiente
           Questi comandi dovrebbero essere specificati da coppie.  Ciò può essere usato per
           specificare i comandi che iniziano o terminano un ambiente letterale.

       Altri
           Vari altri punti sono marcato come TODO (DAFARE) nel sorgente.

BUG CONOSCIUTI

       Vari punti sono marcati come FIXME (AGGIUSTAMI) nel sorgente.

VEDERE ANCHE

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

AUTORI

        Nicolas François <nicolas.francois@centraliens.net>

TRADUZIONE

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

COPYRIGHT E LICENZA

       Copyright © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.

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