Provided by: po4a_0.23-1_all bug

NOM
       Locale::Po4a::Xml - Converteix documents XML i derivats des de/a
       fitxers PO


DESCRIPCIÓ
       L’objectiu del projecte po4a (po per a tot) és facilitar la traducció
       (i sobretot el manteniment de les traduccions) utilitzant les eines de
       gettext en àrees on no eren d’esperar, com ara en la documentació.

       Locale::Po4a::XmL és un mòdul per ajudar en la traducció de documents
       XML a altres llenguatges [humans]. També es pot utilitzar com a base
       per construir mòduls per documents basats en XML.

       Tingueu en compte que aquest mòdul encara està en desenvolupament, i no
       es distribueix en les versions oficials de po4a perquè creiem que
       encara no és prou madur. Si el voleu provar de totes maneres, agafeu-lo
       del CVS.


TRADUINT AMB PO4A::XML
       Aquest mòdul es pot utilitzar directament per tractar documents XML
       genèrics.  Aquest extraurà el contingut de tots els tags, i cap
       atribut, ja que aquí és on s’escriu el text en la majoria de documents
       basats en XML.

       Hi ha algunes opcions (descrites a la propera secció) que permeten
       personalitzar aquest comportament.  Si això no acaba d’encaixar amb el
       vostre format de document, us animo a escriure el vostre propi mòdul
       derivat d’aquest, per descriure els detalls del vostre format.
       Consulteu la secció "Escrivint mòduls derivats" més avall, per la
       descripció del procés.


OPCIONS QUE ACCEPTA AQUEST MÃ’DUL
       L’opció global de depuració fa que aquest mòdul mostri les cadenes
       excloses, per tal de comprovar si se salta quelcom important.

       Aquestes són les opcions particulars d’aquest mòdul:

       nostrip
           Evita que es netegin els espais al voltant de les cadenes extretes.

       wrap
           Canonitza les cadenes a traduir, considerant que els espais no són
           importants, i justifica el document traduït. Aquest comportament es
           pot modificar des de les opcions personalitzades de cada tag. Vegeu
           l’opció "tags" de més avall.

       caseinsensitive
           Fa que la cerca de tags i atributs es faci independentment de
           majúscules i minúscules.  Si està definit, tractarà els tags
           <BooK>laNG i <BOOK>Lang com <book>lang.

       tagsonly
           Extracts only the specified tags in the "tags" option.  Otherwise,
           it will extract all the tags except the ones specified.

       doctype
           Cadena que s’intentarà encaixar amb la primera línia del tipus de
           document (si està definit). Si falla, es considerarà que el
           document és de tipus erroni.

       tags
           Llista separada per espais dels tags que voleu traduir o saltar.
           Per defecte, els tags especificats s’exclouran, però si utilitzeu
           l’opció "tagsonly", els tags especificats seran els únics inclosos.
           Els tags han d’estar en la forma <aaa>, però podeu ajuntar-ne
           alguns (<bbb><aaa>) per dir que només s’ha de traduir el contingut
           del tag <aaa> quan estigui dins d’un tag <bbb>.

           També podeu especificar algunes opcions de cada tag posant alguns
           caràcters davant de la gerarquia de tags. Per exemple, podeu posar
           ’w’ (wrap, justificar) o ’W’ (no justificar)  per saltar el
           comportament per defecte especificat en l’opció global "wrap".

           Exemple: W<chapter><title>

       attributes
           Llista separada per espais dels atributs dels tags que voleu
           traduir.  Podeu especificar els atributs pel seu nom (per exemple,
           "lang"), però també podeu prefixar-los amb una jerarquia de tags,
           per especificar que només es tradueixi quan estigui dins del tag
           especificat. Per exemple: <bbb><aaa>lang especifica que l’atribut
           lang només es traduirà quan estigui dins d’un tag <aaa>, i aquest
           estigui dins d’un tag <bbb>.

       inline
           Llista separada per espais dels tags que voleu tractar com a inline
           (que no trenquin la seqüència).  Per defecte, tots els tags
           trenquen la seqüència.  Aquesta opció segueix la mateixa sintaxi de
           l’opció tags.

       nodefault
           Space separated list of tags that the module should not try to set
           by default in the "tags" or "inline" category.


ESCRIVINT MÃ’DULS DERIVATS
       DEFINIR ELS TAGS I ATRIBUTS A TRADUIR

       La personalització més simple tracta de definir quins tags i atributs
       voleu que l’analitzador tradueixi.  Això s’ha de fer en la funció
       initialize.  Primer haureu de cridar l’initialize principal, per tal
       d’obtenir les opcions de la línia de comandes, i després afegir les
       definicions personalitzades al hash d’opcions.  Si voleu tractar
       algunes opcions noves de la línia de comandes, haureu de definir-les
       abans de cridar l’initialize principal:

         $self->{options}{’nova_opcio’}=’’;
         $self->SUPER::initialize(%options);
         $self->{options}{’tags’}.=’ <p> <head><title>’;
         $self->{options}{’attributes’}.=’ <p>lang id’;
         $self->{options}{’inline’}.=’ <br>’;
         $self->treat_options;

       REESCRIVINT LA FUNCIÓ found_string

       Una altra forma simple és sobreescriure la funció "found_string", que
       rep les cadenes que extreu l’analitzador, per tal de traduir-les.  Aquí
       podeu controlar quines cadenes voleu traduir, i aplicar-los
       transformacions abans i després de la mateixa traducció.

       Rep el text extret, la referència d’on s’ha trobat, i un hash que conté
       informació extra per controlar quines cadenes s’han de traduir, com
       traduir-les, i com generar el comentari.

       El contingut d’aquestes opcions depèn del tipus de cadena que sigui
       (especificat en una entrada d’aquest hash):

       type="tag"
           La cadena trobada és el contingut d’un tag traduïble. L’entrada
           "tag_options" conté els caràcters d’opcions de davant la jerarquia
           de tags de l’opció "tags" del mòdul.

       type="attribute"
           Significa que la cadena trobada és el valor d’un atribut traduïble.
           L’entrada "attribute" conté el nom de l’atribut.

       Ha de retornar el text que reemplaçarà l’original al document traduït.
       Aquí hi ha un exemple bàsic d’aquesta funció:

         sub found_string {
           my ($self,$text,$ref,$opcions)=@_;
           $text = $self->translate($text,$ref,"type ".$opcions->{’type’},
             ’wrap’=>$self->{options}{’wrap’});
           return $text;
         }

       Podeu trobar un altre exemple simple en el mòdul de Dia, que tan sols
       filtra algunes cadenes.

       MODIFICANT ELS TIPUS DE TAGS (PER FER)

       Aquesta és més complexa, però permet una personalització (pràcticament)
       total.  Està basada en una llista de hashs, on cadascun defineix el
       comportament d’un tipus de tag. La llista ha d’estar ordenada de forma
       que els tags més generals apareguin després dels més concrets (ordenats
       primer per la clau de principi i després per la de final). Per definir
       un tipus de tag haureu de construir un hash amb les següents claus:

       beginning
           Especifica el principi del tag, després de "<".

       end Especifica el final del tag, abans de ">".

       breaking
           Indica si aquesta classe de tags és trencadora.  Un tag no-
           trencador (inline) és un que es pot agafar com a part del contingut
           d’un altre tag.  Pot prendre els valors fals (0), cert (1) o
           indefinit.  Si el deixeu indefinit, haureu de definir la funció
           f_breaking que dirà si un tag concret d’aquesta classe és trencador
           o no.

       f_breaking
           És una funció que dirà si el següent tag és trencador o no.  S’ha
           de definir si l’opció "breaking" no ho està.

       f_extract
           Si deixeu aquesta funció indefinida, la funció d’extracció genèrica
           s’encarregarà d’extreure aquests tags.  És útil per tags que poden
           contenir altres tags o estructures especials a dins, per tal que
           l’analitzador principal no es torni boig.  Aquesta funció rep un
           booleà que indica si el tag s’ha d’eliminar de la seqüència
           d’entrada o no.

       f_translate
           Aquesta funció rep el tag (en el format de get_string_until()) i
           retorna el tag traduït (amb els atributs traduïts o totes les
           transformacions necessàries) com una única cadena.


FUNCIONS INTERNES utilitzades per escriure analitzadors derivats
       TREBALLANT AMB TAGS

       get_path()
           Aquesta funció retorna el camí des de l’arrel del document fins al
           tag actual, de la forma <html><body><p>.

       tag_type()
           Aquesta funció retorna l’índex de la llista tag_types que encaixa
           amb el següent tag de la seqüència d’entrada, o -1 si s’ha arribat
           al final del document d’entrada.

       extract_tag($$)
           Aquesta funció retorna el següent tag de la seqüència d’entrada
           sense el principi i el final, en forma de vector, per tal de
           mantenir les referències del fitxer d’entrada.  Té dos paràmetres:
           el tipus del tag (de la forma retornada per tag_type) i un booleà,
           que indica si s’ha d’eliminar de la seqüència d’entrada.

       get_tag_name(@)
           Aquesta funció retorna el nom del tag passar com a paràmetre, en la
           forma de vector retornat per extract_tag.

       breaking_tag()
           Aquesta funció retorna un booleà que diu si el següent tag de la
           seqüència d’entrada és un tag trencador de seqüència o no (tag
           inline).  Deixa la seqüència d’entrada intacta.

       treat_tag()
           Aquesta funció tradueix el següent tag de la seqüència d’entrada.
           Utilitza les funcions de traducció personalitzades de cada tipus de
           tag.

       tag_in_list($@)
           Aquesta funció retorna una cadena que indica si el primer paràmetre
           (una jerarquia de tags) encaixa amb algun dels tags del segon
           paràmetre (una llista de tags o jerarquies de tags). Si no encaixa,
           retorna 0. En cas contrari, retorna les opcions del tag encaixat
           (els caràcters davant del tag) o 1 (si el tag no té opcions).

       TREBALLANT AMB ATRIBUTS

       treat_attributes(@)
           Aquesta funció tracta la traducció dels atributs dels tags. Rep un
           tag sense les marques de principi i final, busca els atributs, i
           tradueix els traduïbles (especificats a l’opció "attributes" del
           mòdul).  Retorna una cadena plana amb el tag traduït.

       TREBALLANT AMB LES OPCIONS DELS MÃ’DULS

       treat_options()
           Aquesta funció omple les estructures internes que contenen els
           tags, atributs i dades inline amb les opcions del mòdul
           (especificades a la línia de comandes o a la funció
           d’inicialització).

       OBTENINT TEXT DEL DOCUMENT Dâ€â€™ENTRADA

       get_string_until($%)
           Aquesta funció retorna un vector amb les línies (i les referències)
           del document d’entrada fins que troba el primer paràmetre.  El
           segon paràmetre és un hash d’opcions. El valor 0 significa
           desactivat (per defecte) i 1, activat.

           Les opcions vàlides són:

           include
               Fa que la cadena retornada contingui el text buscat

           remove
               Elimina de l’entrada la cadena retornada

           unquoted
               Assegura que el text buscat no està envoltat de cometes

       skip_spaces(\@)
           Aquesta funció rep com a paràmetre la referència a un paràgraf (en
           el format retornat per get_string_until), se salta els espais del
           principi, i els retorna com una cadena simple.

       join_lines(@)
           Aquesta funció retorna una cadena simple amb el text del vector de
           paràmetre (descartant les referències).

ESTAT Dâ€â€™AQUEST MÃ’DUL
       Aquest mòdul pot traduir tags i atributs.

       El suport d’entitats i fitxers inclosos està a la llista de tasques
       pendents.

       L’escriptura de mòduls derivats encara és força limitada.


LLISTA DE TASQUES PENDENTS
       DOCTYPE (ENTITATS)

       There is a minimal support for the translation of entities. They are
       translated as a whole, and tags are not taken into account. Multilines
       entities are not supported and entities are always rewrapped during the
       translation.

       FITXERS INCLOSOS

       MODIFICAR ELS TIPUS DE TAGS DES DELS MÃ’DULS HEREDATS (moure
       l’estructura tag_types dins del hash $self?)

       tag trencador dins d’un tag no-trencador (possible?) provoca comentaris
       lletjos


CONSULTEU TAMBÉ
       po4a(7), Locale::Po4a::TransTractor(3pm).


AUTORS
        Jordi Vilalta <jvprat@gmail.com>


TRADUCCIÓ
        Carme Cirera <menxu@hotmail.com>
        Jordi Vilalta <jvprat@gmail.com>


DRET DE CÒPIA I LLICÈNCIA
       Copyright (c) 2004 per Jordi Vilalta <jvprat@gmail.com>

       Aquest programa és programari lliure; podeu redistribuir-lo i/o
       modificar-lo sota els termes de la GPL (consulteu el fitxer COPYING).