Provided by: po4a_0.66-1_all 
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 dei comandi definiti nelle liste
predefinite.
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 permette di descrivere in dettaglio i parametri del comando comando1. Questa informazione
verrà usata per controllare il numero di argomenti ed il loro tipo.
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ò permette di mantenere più contesto, ed è utile per comandi con
piccole parole nei parametri, che possono avere significati multipli (e traduzioni).
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 permette di definire i parametri accettati dall'ambiente env. Questa informazione viene in
seguito usata per controllare il numero di argomenti del comando \begin e permette di specificare
cosa deve essere tradotto. 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
Aggiungi 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ò potrebbe consentire di 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 (vedere il file COPYING).
Strumenti Po4a 2022-01-02 Locale::Po4a::TeX(3pm)