attributes Elenco separato da spazi di attributi del tag che si desidera tradurre. Si puo specificare gli attributi in base al loro nome (ad esempio, "lang"), ma si puo anche anteporre una gerarchia di tag, per specificare che questo attributo verra tradotto solo quando si trova nel tag specificato. Ad esempio: <bbb><aaa>lang specifica che l'attributo lang verra tradotto solo se si trova in un tag <aaa> in un tag <bbb>. foldattributes Non tradurre gli attributi nei tag in linea. Invece, sostituisci tutti gli attributi di un tag con po4a-id=<id>. Utile quando gli attributi non devono essere tradotti, poiche semplifica le stringhe per i traduttori ed evita errori di battitura. customtag Elenco separato da spazi di tag che non devono essere trattati come tag. Questi tag sono trattati come in linea e non devono essere chiusi. break Elenco separato da spazi di tag che dovrebbero interrompere la sequenza. Per impostazione predefinita, tutti i tag interrompono la sequenza. I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando si trova all'interno di un altro tag (<bbb>). Tenere presente che un tag deve essere elencato solo in una delle stringhe di impostazione break, inline placeholder o customtag. inline Elenco separato da spazi di tag che devono essere trattati come in linea. Per impostazione predefinita, tutti i tag interrompono la sequenza. I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando si trova all'interno di un altro tag (<bbb>). placeholder Elenco separato da spazi di tag che devono essere trattati come segnaposto. I segnaposto non interrompono la sequenza, ma il contenuto dei segnaposto viene tradotto separatamente. La posizione del segnaposto nel suo blocco sara contrassegnata da una stringa simile a: <placeholder type=\"footnote\" id=\"0\"/> I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando si trova all'interno di un altro tag (<bbb>). break-pi Per impostazione predefinita, le istruzioni di elaborazione (ovvero i tag "<? ... ?>") vengono gestite come tag in linea. Passare questa opzione se si vuole che il PI venga gestito come tag di rottura. Si noti che i tag PHP non elaborati vengono gestiti come istruzioni di elaborazione dall'analizzatore. nodefault Elenco di tag separati da spazi che il modulo non dovrebbe provare a impostare per impostazione predefinita in nessuna categoria. Se si ha un tag che ha la sua impostazione predefinita dalla sottoclasse di questo modulo ma si vuole impostare un'impostazione alternativa, si deve elencare quel tag come parte della stringa di impostazione nodefault. cpp Supporta le direttive del preprocessore C. Quando questa opzione e impostata, po4a considerera le direttive del preprocessore come separatori di paragrafo. Cio e importante se il file XML deve essere preprocessato perche altrimenti le direttive potrebbero essere inserite in mezzo alle righe, se po4a le considerasse appartenenti al paragrafo corrente, e quindi non verrebbero riconosciute dal preprocessore. Nota: le direttive del preprocessore devono apparire solo tra i tag (non devono interrompere un tag). translated Elenco separato da spazi di marcatori che si intende tradurre. I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando si trova all'interno di un altro tag (<bbb>). Si puo inoltre specificare alcune opzioni di tag, inserendo alcuni caratteri davanti alla gerarchia dei tag. Cio supera il comportamento predefinito specificato dalle opzioni globali wrap e defaulttranslateoption. w I tag devono essere tradotti e il contenuto puo essere riformattatato. W I tag devono essere tradotti e il contenuto non puo essere riformattatato. i I tag devono essere tradotti in linea. p I tag devono essere tradotti come segnaposto. Internamente, l'analizzatore XML si preoccupa solo di queste quattro opzioni: w W i p. * I tag elencati in break sono impostati a w o W a seconda dell'opzione wrap. * I tag elencati in inline sono impostati a i. * I tag elencati in placeholder sono impostati a p. * I tag elencati in untranslated sono senza alcuna di queste opzioni impostate. E possibile verificare il comportamento effettivo dei parametri interni invocando po4a con l'opzione --debug. Esempio: W<chapter><title> Si noti che un tag va elencato nella stringa di impostazione translated o untranslated. untranslated Elenco separato da spazi di marcatori che non si intende tradurre. I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando si trova all'interno di un altro tag (<bbb>). Si noti che un tag in linea traducibile in un tag non tradotto viene trattato come un tag di rottura traducibile, l'impostazione i viene eliminata e w o W viene impostato a seconda dell'opzione wrap. defaulttranslateoption Le categorie predefinite, per i tag che non fanno parte di translated, untranslated, break, inline o placeholder. E un insieme di lettere come definito in translated e questa impostazione e valida solo per i tag traducibili. SCRIVERE MODULI DERIVATI DEFINIRE CHE MARCATORI E ATTRIBUTI TRADURRE La personalizzazione piu semplice consiste nel definire quali tag e attributi si desidera che l'analizzatore traduca. Cio dovrebbe essere fatto nella funzione di inizializzazione. Per prima cosa si dovrebbe chiamare l'inizializzazione principale, per ottenere le opzioni della riga di comando, quindi aggiungere le proprie definizioni personalizzate all'hash delle opzioni. Se vuole trattare alcune nuove opzioni dalla riga di comando, si deve definirle prima di chiamare l'inizializzazione principale: $self->{options}{'new_option'}=''; $self->SUPER::initialize(%options); $self->{options}{'_default_translated'}.=' <head><title>'; $self->{options}{'attributes'}.=' lang id'; $self->{options}{'_default_inline'}.=' '; $self->treat_options; Si dovrebbe usare le opzioni _default_inline, _default_break, _default_placeholder, _default_translated, _default_untranslated e _default_attributes nei moduli derivati. Cio consente di superare il comportamento predefinito definito nel modulo, con le opzioni a riga di comando. SUPERARE IL COMPORTAMENTO PREDEFINITO CON OPZIONI DA RIGA DI COMANDO Se non ci piace il comportamento predefinito di questo modulo xml e dei suoi moduli derivati, si puo fornire delle opzioni a riga di comando per modificarne il comportamento. Consultare Locale::Po4a::Docbook(3pm), OVERRIDING THE found_string FUNCTION Un altro semplice passo e fare l'override della funzione "found_string", che riceve le stringhe estratte dall'analizzatore, in modo da tradurle. Li si puo controllare quali stringhe si vuole tradurre ed eseguire trasformazioni su esse, prima o dopo la traduzione stessa. Riceve il testo estratto, il riferimento su dove si trovava e un hash che contiene informazioni extra per controllare quali stringhe tradurre, come tradurle e generare il commento. Il contenuto di queste opzioni dipende dal tipo di stringa (specificato in una voce di questo hash): type="tag" La stringa trovata e il contenuto di un tag traducibile. La voce "tag_options" contiene i caratteri dell'opzione prima della gerarchia delle variabili nell'opzione "tag" del modulo. type="attributo" Significa che la stringa trovata e il valore di un attributo traducibile. La voce "attributo" ha il nome dell'attributo. Deve restituire il testo che sostituira l'originale nel documento tradotto. Ecco un esempio di base di questa funzione: sub found_string { my ($self,$text,$ref,$options)=@_; $text = $self->translate($text,$ref,"type ".$options->{'type'}, 'wrap'=>$self->{options}{'wrap'}); return $text; } C'e un altro semplice esempio nel nuovo modulo Dia, che filtra solo alcune stringhe. MODIFICA DEI TIPI DI TAG (TODO) Questo e piu complesso, ma consente una personalizzazione (quasi) totale. Si basa su un elenco di hash, ognuno dei quali definisce il comportamento di un tipo di tag. L'elenco dovrebbe essere ordinato in modo che i tag piu generali vengano dopo quelli piu specifici (ordinati prima per l'inizio e poi per le chiavi di fine). Per definire un tipo di tag si dovra creare un hash con le seguenti chiavi: beginning Specifica l'inizio del tag, dopo del "<". end Specifica la fine del tag, prima del ">". breaking Indica se la classe tag e una classe di tag di interruzione (breaking). Un tag di non interruzione (non-breaking) (in linea) e untag che puo essere preso come parte del contenuto di un altro tag. Puo assumere i valori falso (0), vero (1) o non definito. Se si lascia indefinito, si dovra definire la funzione f_breaking che dira se un tag effettivamente di questa classe e un tag di interruzione o meno. f_breaking E una funzione che dira se il tag successivo e di interruzione o meno. Dovrebbe essere definita se l'opzione breaking non lo e. f_extract Se si lascia questa chiave indefinita, la funzione di estrazione generica dovra estrarre il tag stesso. E utile per i tag che possono avere altri tag o strutture speciali al loro interno, in modo che l'analizzatore principale non vada in confusione. Questa funzione riceve un booleano che dice se il tag deve essere rimosso o meno dal flusso di ingresso. f_translate Questa funzione riceve il tag (nel formato get_string_until()) e restituisce il tag tradotto (attributi tradotti o tutte le trasformazioni necessarie) in forma di stringa singola. FUNZIONI INTERNE usate per scrivere parser derivati LAVORARE CON I TAG get_path() Questa funzione restituisce il percorso del tag corrente dalla radice del documento, nella forma <html><body>. Si puo passare come argomento anche una schiera array di tag (senza parentesi) aggiuntivi. Questi elementi del percorso vengono aggiunti alla fine del percorso corrente. tag_type() Questa funzione restituisce l'indice dall'elenco tag_types che si adatta al tag successivo nel flusso di ingresso o -1 se si trova alla fine del file di ingresso. Qui, il tag ha una struttura che inizia con < e finisce con > e puo contenere piu righe. Questo funziona sull'array "@{$self->{TT}{doc_in}}" che contiene i dati del documento in ingresso e fa riferimento indirettamente tramite "$self->shiftline()" e "$self- >unshiftline($$)". extract_tag($$) Questa funzione restituisce il tag successivo dal flusso di ingresso senza l'inizio e la fine, in forma di matrice, per mantenere i riferimenti dal file di ingresso. Ha due parametri: il tipo del tag (come restituito da tag_type) e un valore booleano, che indica se deve essere rimosso dal flusso di ingresso. Questo funziona sull'array "@{$self->{TT}{doc_in}}" che contiene i dati del documento in ingresso e fa riferimento indirettamente tramite "$self->shiftline()" e "$self- >unshiftline($$)". get_tag_name(@) Questa funzione restituisce il nome del tag passato come argomento, nel formato array restituito da extract_tag. breaking_tag() Questa funzione restituisce un valore booleano che dice se il tag successivo nel flusso di ingresso e un tag di interruzione o meno (tag in linea). Lascia intatto il flusso di ingresso. treat_tag() Questa funzione traduce il tag successivo dal flusso di ingresso. Usata dalle funzioni di traduzione personalizzate di tutti i tipi di tag. Questo funziona sull'array "@{$self->{TT}{doc_in}}" che contiene i dati del documento in ingresso e fa riferimento indirettamente tramite "$self->shiftline()" e "$self- >unshiftline($$)". tag_in_list($@) Questa funzione restituisce un valore stringa che indica se il primo argomento (una gerarchia di tag) corrisponde a uno dei tag del secondo argomento (un elenco di tag o gerarchie di tag). Se non corrisponde, restituisce 0. Altrimenti, restituisce le opzioni del tag corrispondente (i caratteri davanti al tag) o 1 (se quel tag non ha opzioni). LAVORARE CON GLI ATTRIBUTI treat_attributes(@) Questa funzione gestisce la traduzione degli attributi dei tag. Riceve il tag senza i segni di inizio/fine, quindi trova gli attributi e traduce quelli traducibili (specificati dall'opzione del modulo attributes). Cio restituisce una stringa semplice con il tag tradotto. LAVORARE CON CONTENUTI MARCATI treat_content() Questa funzione ottiene il testo fino al successivo tag di interruzione (non in linea) dal flusso di ingresso. La si traduca usando le funzioni di traduzione personalizzate di ciascun tipo di tag. Questo funziona sull'array "@{$self->{TT}{doc_in}}" che contiene i dati del documento in ingresso e fa riferimento indirettamente tramite "$self->shiftline()" e "$self- >unshiftline($$)". LAVORARE CON LE OPZIONI DEL MODULO treat_options() Questa funzione riempie le strutture interne che contengono i tag, gli attributi e i dati in linea con le opzioni del modulo (specificate nella riga di comando o nella funzione di inizializzazione). RICAVARE IL TESTO DAL DOCUMENTO IN INGRESSO get_string_until($%) Questa funzione restituisce un array con le righe (e i riferimenti) dal documento di ingresso finche non trova il primo argomento. Il secondo argomento e un hash di opzioni. Il valore 0 significa disabilitata (valore predefinito) e 1, abilitata. Le opzioni valide sono: include Questo fa in modo che l'array restituito contenga il testo cercato remove Questo rimuove il flusso restituito dall'ingresso unquoted Questo si assicura che il testo cercato sia fuori da ogni virgolettatura regex Indica che il primo argomento e un'espressione regolare piuttosto che una semplice stringa skip_spaces(\@) Questa funzione riceve come argomento il riferimento a un paragrafo (nel formato restituito da get_string_until), salta i suoi spazi di intestazione e li restituisce come stringa semplice. join_lines(@) Questa funzione restituisce una stringa semplice con il testo dall'array di argomenti (senza i riferimenti). STATO DI QUESTO MODULO Questo modulo puo tradurre tag e attributi. ELENCO DEI DAFARE TIPO DI DOCUMENTO (ENTITA) C'e un supporto minimo per la traduzione di entita. Vengono tradotte in un blocco e i tag non vengono presi in considerazione. Le entita multilinea non sono supportate; le entita vengono sempre riformattate durante la traduzione. MODIFICA I TIPI DI TAG DAI MODULI EREDITATI (sposta la struttura tag_types all'interno dell'hash $self?) VEDERE ANCHE Locale::Po4a::TransTractor(3pm), po4a(7) AUTORI Jordi Vilalta <jvprat@gmail.com> Nicolas Francois <nicolas.francois@centraliens.net> TRADUZIONE Danilo Piazzalunga <danilopiazza@libero.it> Marco Ciampa <ciampix@posteo.net> COPYRIGHT E LICENZA Copyright (C) 2004 by Jordi Vilalta <jvprat@gmail.com> Copyright (C) 2008-2009 by Nicolas Francois <nicolas.francois@centraliens.net> Questo programma e software libero; e lecito ridistribuirlo o modificarlo secondo i termini della licenza GPL v2.0 o successive (vedere il file COPYING). perl v5.38.2 2024-06-26 LOCALE::PO4A::XML.3PM(1)

LOCALE::PO4A::XML.3PM(1) User Contributed Perl Documentation NOME Locale::Po4a::Xml - converte documenti XML e derivati da/verso file PO DESCRIZIONE L'obiettivo del progetto po4a (PO per tutto) e di facilitare le traduzioni (e cosa piu interessante, la manutenzione delle traduzioni) usando gli strumenti associati a gettext in aree inaspettate come la documentazione. Locale::Po4a::Xml e un modulo che aiuta la traduzione in altre lingue della documentazione in formato XML. Puo anche essere usato come base per scrivere moduli per documenti basati su XML. TRADURRE CON PO4A::XML Questo modulo puo essere utilizzato direttamente per gestire documenti XML generici. Estrarra tutto il contenuto del tag e nessun attributo, poiche e li che viene scritto il testo nella gran parte dei documenti basati su XML. 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 piu sotto, per la descrizione del processo. OPZIONI ACCETTATE DA QUESTO MODULO L'opzione di debug globale fa si che questo modulo mostri le stringhe escluse, per vedere se salta qualcosa di importante. Queste sono le opzioni speciali per questo modulo: nostrip Previene la rimozione degli spazi attorno alle stringhe estratte. wrap Canonizza la stringa da tradurre, considerando che gli spazi bianchi non siano importanti, e formatta il documento tradotto. Questa opzione puo essere superata da opzioni tag personalizzate. Vedere l'opzione translated sotto. unwrap_attributes Gli attributi vengono formattati per impostazione predefinita. Questa opzione disabilita la formattazione. caseinsensitive Fa in modo che la ricerca di tag e attributi funzioni senza distinzione tra maiuscole e minuscole. Se e definito, trattera laNG ed Lang come lang. escapequotes Virgolette di escape nelle stringhe in uscita. Necessario, ad esempio, per creare risorse stringa da utilizzare con gli strumenti di build Android. Vedere anche: https://developer.android.com/guide/topics/resources/string-resource.html includeexternal Se definite, le entita esterne verranno incluse nel documento generato (tradotto) e per l'estrazione delle stringhe. Se non e definito, si dovra tradurre gli elementi esterni separatamente come documenti indipendenti. ontagerror Questa opzione definisce il comportamento del modulo quando incontra una sintassi XML non valida (un tag di chiusura che non corrisponde all'ultimo tag di apertura). Puo assumere i seguenti valori: fail Questo e il valore predefinito. Il modulo uscira con un errore. warn L'esecuzione del modulo continuera, e generera un avvertimento. silent Il modulo continuera senza alcun avvertimento. Attenzione a usare questa opzione. Generalmente si raccomanda di sistemare il file in ingresso. tagsonly Nota: questa opzione e sconsigliata. Estrae solo i tag specificati nell'opzione tags. Altrimenti, estrarra tutti i tag tranne quelli specificati. doctype Stringa di cui verra verificata la corrispondenza con la prima riga del doctype del documento (se definito). Nel caso non corrisponda, un avviso indichera che il documento potrebbe essere di tipo non valido. addlang Stringa indicante il percorso (es. ) di un tag a cui deve essere aggiunto un attributo lang="...". La lingua sara definita come il nome di base del file PO senza alcuna estensione .po. optionalclosingtag Valore booleano indicante se i tag di chiusura sono facoltativi (come in HTML). Per impostazione predefinita, i tag di chiusura mancanti generano un errore gestito secondo ontagerror. tags Nota: questa opzione e sconsigliata. In alternativa si consiglia di usare le opzioni translated e untranslated. Elenco separato da spazi di tag che si vuole tradurre o saltare. Per impostazione predefinita, i tag specificati verranno esclusi, ma se si usa l'opzione "tagsonly", i tag specificati saranno gli unici inclusi. I tag devono essere nella forma , ma si puo unirne alcuni () per dire che il contenuto del tag verra tradotto solo quando e in un tag . Si puo anche specificare alcune opzioni di tag inserendo alcuni caratteri davanti alla gerarchia dei tag. Ad esempio, si puo inserire w (a capo) o W (non a capo) per sovrascrivere il comportamento predefinito specificato dall'opzione globale wrap. Esempio: W attributes Elenco separato da spazi di attributi del tag che si desidera tradurre. Si puo specificare gli attributi in base al loro nome (ad esempio, "lang"), ma si puo anche anteporre una gerarchia di tag, per specificare che questo attributo verra tradotto solo quando si trova nel tag specificato. Ad esempio: <bbb><aaa>lang specifica che l'attributo lang verra tradotto solo se si trova in un tag <aaa> in un tag <bbb>. foldattributes Non tradurre gli attributi nei tag in linea. Invece, sostituisci tutti gli attributi di un tag con po4a-id=<id>. Utile quando gli attributi non devono essere tradotti, poiche semplifica le stringhe per i traduttori ed evita errori di battitura. customtag Elenco separato da spazi di tag che non devono essere trattati come tag. Questi tag sono trattati come in linea e non devono essere chiusi. break Elenco separato da spazi di tag che dovrebbero interrompere la sequenza. Per impostazione predefinita, tutti i tag interrompono la sequenza. I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando si trova all'interno di un altro tag (<bbb>). Tenere presente che un tag deve essere elencato solo in una delle stringhe di impostazione break, inline placeholder o customtag. inline Elenco separato da spazi di tag che devono essere trattati come in linea. Per impostazione predefinita, tutti i tag interrompono la sequenza. I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando si trova all'interno di un altro tag (<bbb>). placeholder Elenco separato da spazi di tag che devono essere trattati come segnaposto. I segnaposto non interrompono la sequenza, ma il contenuto dei segnaposto viene tradotto separatamente. La posizione del segnaposto nel suo blocco sara contrassegnata da una stringa simile a: <placeholder type=\"footnote\" id=\"0\"/> I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando si trova all'interno di un altro tag (<bbb>). break-pi Per impostazione predefinita, le istruzioni di elaborazione (ovvero i tag "<? ... ?>") vengono gestite come tag in linea. Passare questa opzione se si vuole che il PI venga gestito come tag di rottura. Si noti che i tag PHP non elaborati vengono gestiti come istruzioni di elaborazione dall'analizzatore. nodefault Elenco di tag separati da spazi che il modulo non dovrebbe provare a impostare per impostazione predefinita in nessuna categoria. Se si ha un tag che ha la sua impostazione predefinita dalla sottoclasse di questo modulo ma si vuole impostare un'impostazione alternativa, si deve elencare quel tag come parte della stringa di impostazione nodefault. cpp Supporta le direttive del preprocessore C. Quando questa opzione e impostata, po4a considerera le direttive del preprocessore come separatori di paragrafo. Cio e importante se il file XML deve essere preprocessato perche altrimenti le direttive potrebbero essere inserite in mezzo alle righe, se po4a le considerasse appartenenti al paragrafo corrente, e quindi non verrebbero riconosciute dal preprocessore. Nota: le direttive del preprocessore devono apparire solo tra i tag (non devono interrompere un tag). translated Elenco separato da spazi di marcatori che si intende tradurre. I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando si trova all'interno di un altro tag (<bbb>). Si puo inoltre specificare alcune opzioni di tag, inserendo alcuni caratteri davanti alla gerarchia dei tag. Cio supera il comportamento predefinito specificato dalle opzioni globali wrap e defaulttranslateoption. w I tag devono essere tradotti e il contenuto puo essere riformattatato. W I tag devono essere tradotti e il contenuto non puo essere riformattatato. i I tag devono essere tradotti in linea. p I tag devono essere tradotti come segnaposto. Internamente, l'analizzatore XML si preoccupa solo di queste quattro opzioni: w W i p. * I tag elencati in break sono impostati a w o W a seconda dell'opzione wrap. * I tag elencati in inline sono impostati a i. * I tag elencati in placeholder sono impostati a p. * I tag elencati in untranslated sono senza alcuna di queste opzioni impostate. E possibile verificare il comportamento effettivo dei parametri interni invocando po4a con l'opzione --debug. Esempio: W<chapter><title> Si noti che un tag va elencato nella stringa di impostazione translated o untranslated. untranslated Elenco separato da spazi di marcatori che non si intende tradurre. I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando si trova all'interno di un altro tag (<bbb>). Si noti che un tag in linea traducibile in un tag non tradotto viene trattato come un tag di rottura traducibile, l'impostazione i viene eliminata e w o W viene impostato a seconda dell'opzione wrap. defaulttranslateoption Le categorie predefinite, per i tag che non fanno parte di translated, untranslated, break, inline o placeholder. E un insieme di lettere come definito in translated e questa impostazione e valida solo per i tag traducibili. SCRIVERE MODULI DERIVATI DEFINIRE CHE MARCATORI E ATTRIBUTI TRADURRE La personalizzazione piu semplice consiste nel definire quali tag e attributi si desidera che l'analizzatore traduca. Cio dovrebbe essere fatto nella funzione di inizializzazione. Per prima cosa si dovrebbe chiamare l'inizializzazione principale, per ottenere le opzioni della riga di comando, quindi aggiungere le proprie definizioni personalizzate all'hash delle opzioni. Se vuole trattare alcune nuove opzioni dalla riga di comando, si deve definirle prima di chiamare l'inizializzazione principale: $self->{options}{'new_option'}=''; $self->SUPER::initialize(%options); $self->{options}{'_default_translated'}.=' <head><title>'; $self->{options}{'attributes'}.=' lang id'; $self->{options}{'_default_inline'}.=' '; $self->treat_options; Si dovrebbe usare le opzioni _default_inline, _default_break, _default_placeholder, _default_translated, _default_untranslated e _default_attributes nei moduli derivati. Cio consente di superare il comportamento predefinito definito nel modulo, con le opzioni a riga di comando. SUPERARE IL COMPORTAMENTO PREDEFINITO CON OPZIONI DA RIGA DI COMANDO Se non ci piace il comportamento predefinito di questo modulo xml e dei suoi moduli derivati, si puo fornire delle opzioni a riga di comando per modificarne il comportamento. Consultare Locale::Po4a::Docbook(3pm), OVERRIDING THE found_string FUNCTION Un altro semplice passo e fare l'override della funzione "found_string", che riceve le stringhe estratte dall'analizzatore, in modo da tradurle. Li si puo controllare quali stringhe si vuole tradurre ed eseguire trasformazioni su esse, prima o dopo la traduzione stessa. Riceve il testo estratto, il riferimento su dove si trovava e un hash che contiene informazioni extra per controllare quali stringhe tradurre, come tradurle e generare il commento. Il contenuto di queste opzioni dipende dal tipo di stringa (specificato in una voce di questo hash): type="tag" La stringa trovata e il contenuto di un tag traducibile. La voce "tag_options" contiene i caratteri dell'opzione prima della gerarchia delle variabili nell'opzione "tag" del modulo. type="attributo" Significa che la stringa trovata e il valore di un attributo traducibile. La voce "attributo" ha il nome dell'attributo. Deve restituire il testo che sostituira l'originale nel documento tradotto. Ecco un esempio di base di questa funzione: sub found_string { my ($self,$text,$ref,$options)=@_; $text = $self->translate($text,$ref,"type ".$options->{'type'}, 'wrap'=>$self->{options}{'wrap'}); return $text; } C'e un altro semplice esempio nel nuovo modulo Dia, che filtra solo alcune stringhe. MODIFICA DEI TIPI DI TAG (TODO) Questo e piu complesso, ma consente una personalizzazione (quasi) totale. Si basa su un elenco di hash, ognuno dei quali definisce il comportamento di un tipo di tag. L'elenco dovrebbe essere ordinato in modo che i tag piu generali vengano dopo quelli piu specifici (ordinati prima per l'inizio e poi per le chiavi di fine). Per definire un tipo di tag si dovra creare un hash con le seguenti chiavi: beginning Specifica l'inizio del tag, dopo del "<". end Specifica la fine del tag, prima del ">". breaking Indica se la classe tag e una classe di tag di interruzione (breaking). Un tag di non interruzione (non-breaking) (in linea) e untag che puo essere preso come parte del contenuto di un altro tag. Puo assumere i valori falso (0), vero (1) o non definito. Se si lascia indefinito, si dovra definire la funzione f_breaking che dira se un tag effettivamente di questa classe e un tag di interruzione o meno. f_breaking E una funzione che dira se il tag successivo e di interruzione o meno. Dovrebbe essere definita se l'opzione breaking non lo e. f_extract Se si lascia questa chiave indefinita, la funzione di estrazione generica dovra estrarre il tag stesso. E utile per i tag che possono avere altri tag o strutture speciali al loro interno, in modo che l'analizzatore principale non vada in confusione. Questa funzione riceve un booleano che dice se il tag deve essere rimosso o meno dal flusso di ingresso. f_translate Questa funzione riceve il tag (nel formato get_string_until()) e restituisce il tag tradotto (attributi tradotti o tutte le trasformazioni necessarie) in forma di stringa singola. FUNZIONI INTERNE usate per scrivere parser derivati LAVORARE CON I TAG get_path() Questa funzione restituisce il percorso del tag corrente dalla radice del documento, nella forma <html><body>. Si puo passare come argomento anche una schiera array di tag (senza parentesi) aggiuntivi. Questi elementi del percorso vengono aggiunti alla fine del percorso corrente. tag_type() Questa funzione restituisce l'indice dall'elenco tag_types che si adatta al tag successivo nel flusso di ingresso o -1 se si trova alla fine del file di ingresso. Qui, il tag ha una struttura che inizia con < e finisce con > e puo contenere piu righe. Questo funziona sull'array "@{$self->{TT}{doc_in}}" che contiene i dati del documento in ingresso e fa riferimento indirettamente tramite "$self->shiftline()" e "$self- >unshiftline($$)". extract_tag($$) Questa funzione restituisce il tag successivo dal flusso di ingresso senza l'inizio e la fine, in forma di matrice, per mantenere i riferimenti dal file di ingresso. Ha due parametri: il tipo del tag (come restituito da tag_type) e un valore booleano, che indica se deve essere rimosso dal flusso di ingresso. Questo funziona sull'array "@{$self->{TT}{doc_in}}" che contiene i dati del documento in ingresso e fa riferimento indirettamente tramite "$self->shiftline()" e "$self- >unshiftline($$)". get_tag_name(@) Questa funzione restituisce il nome del tag passato come argomento, nel formato array restituito da extract_tag. breaking_tag() Questa funzione restituisce un valore booleano che dice se il tag successivo nel flusso di ingresso e un tag di interruzione o meno (tag in linea). Lascia intatto il flusso di ingresso. treat_tag() Questa funzione traduce il tag successivo dal flusso di ingresso. Usata dalle funzioni di traduzione personalizzate di tutti i tipi di tag. Questo funziona sull'array "@{$self->{TT}{doc_in}}" che contiene i dati del documento in ingresso e fa riferimento indirettamente tramite "$self->shiftline()" e "$self- >unshiftline($$)". tag_in_list($@) Questa funzione restituisce un valore stringa che indica se il primo argomento (una gerarchia di tag) corrisponde a uno dei tag del secondo argomento (un elenco di tag o gerarchie di tag). Se non corrisponde, restituisce 0. Altrimenti, restituisce le opzioni del tag corrispondente (i caratteri davanti al tag) o 1 (se quel tag non ha opzioni). LAVORARE CON GLI ATTRIBUTI treat_attributes(@) Questa funzione gestisce la traduzione degli attributi dei tag. Riceve il tag senza i segni di inizio/fine, quindi trova gli attributi e traduce quelli traducibili (specificati dall'opzione del modulo attributes). Cio restituisce una stringa semplice con il tag tradotto. LAVORARE CON CONTENUTI MARCATI treat_content() Questa funzione ottiene il testo fino al successivo tag di interruzione (non in linea) dal flusso di ingresso. La si traduca usando le funzioni di traduzione personalizzate di ciascun tipo di tag. Questo funziona sull'array "@{$self->{TT}{doc_in}}" che contiene i dati del documento in ingresso e fa riferimento indirettamente tramite "$self->shiftline()" e "$self- >unshiftline($$)". LAVORARE CON LE OPZIONI DEL MODULO treat_options() Questa funzione riempie le strutture interne che contengono i tag, gli attributi e i dati in linea con le opzioni del modulo (specificate nella riga di comando o nella funzione di inizializzazione). RICAVARE IL TESTO DAL DOCUMENTO IN INGRESSO get_string_until($%) Questa funzione restituisce un array con le righe (e i riferimenti) dal documento di ingresso finche non trova il primo argomento. Il secondo argomento e un hash di opzioni. Il valore 0 significa disabilitata (valore predefinito) e 1, abilitata. Le opzioni valide sono: include Questo fa in modo che l'array restituito contenga il testo cercato remove Questo rimuove il flusso restituito dall'ingresso unquoted Questo si assicura che il testo cercato sia fuori da ogni virgolettatura regex Indica che il primo argomento e un'espressione regolare piuttosto che una semplice stringa skip_spaces(\@) Questa funzione riceve come argomento il riferimento a un paragrafo (nel formato restituito da get_string_until), salta i suoi spazi di intestazione e li restituisce come stringa semplice. join_lines(@) Questa funzione restituisce una stringa semplice con il testo dall'array di argomenti (senza i riferimenti). STATO DI QUESTO MODULO Questo modulo puo tradurre tag e attributi. ELENCO DEI DAFARE TIPO DI DOCUMENTO (ENTITA) C'e un supporto minimo per la traduzione di entita. Vengono tradotte in un blocco e i tag non vengono presi in considerazione. Le entita multilinea non sono supportate; le entita vengono sempre riformattate durante la traduzione. MODIFICA I TIPI DI TAG DAI MODULI EREDITATI (sposta la struttura tag_types all'interno dell'hash $self?) VEDERE ANCHE Locale::Po4a::TransTractor(3pm), po4a(7) AUTORI Jordi Vilalta <jvprat@gmail.com> Nicolas Francois <nicolas.francois@centraliens.net> TRADUZIONE Danilo Piazzalunga <danilopiazza@libero.it> Marco Ciampa <ciampix@posteo.net> COPYRIGHT E LICENZA Copyright (C) 2004 by Jordi Vilalta <jvprat@gmail.com> Copyright (C) 2008-2009 by Nicolas Francois <nicolas.francois@centraliens.net> Questo programma e software libero; e lecito ridistribuirlo o modificarlo secondo i termini della licenza GPL v2.0 o successive (vedere il file COPYING). perl v5.38.2 2024-06-26 LOCALE::PO4A::XML.3PM(1)