Provided by: po4a_0.23-1_all bug

NOMBRE

       Locale::Po4a::Xml - Convierte documentos XML y derivados desde/a
       archivos PO

DESCRIPCION

       El objetivo del proyecto po4a (po para todo) es facilitar la traducción
       (y más interesante, el mantenimiento de las traducciones) usando las
       herramientas de gettext en áreas dónde no eran de esperar, como en la
       documentación.

       Locale::Po4a::Xml es un módulo para ayudar en la traducción de
       documentación en el formato XML a otros lenguajes [humanos]. También se
       puede usar como base para construir módulos para documentos basados en
       XML.

       Tenga en cuenta que este módulo aún está en desarrollo, y no se
       distribuye en los lanzamientos oficiales de po4a porque aún no lo
       consideramos suficientemente maduro. Si desea probarlo de todas formas,
       obténgalo del CVS.

TRADUCIENDO CON PO4A::XML

       Este módulo puede usarse directamente para tratar documentos XML
       genéricos. Esto extraerá el contenido de todos los tags, y ningún
       atributo, ya que ahí es donde se escribe el texto en la mayoría de
       documentos basados en XML.

       Hay algunas opciones (descritas en la siguiente sección) que pueden
       personalizar este comportamiento. Si eso no es suficiente para su
       formato de documento, le animo a que escriba su propio módulo derivado
       de éste, para describir los detalles de su formato. Consulte la sección
       "Escribiendo módulos derivados" de más abajo, para una descripción del
       proceso.

OPCIONES ACEPTADAS POR ESTE MODULO

       La opción debug global provoca que este módulo muestre las cadenas
       excluidas, para ver si se salta algo importante.

       Estas son las opciones particulares de este módulo:

       nostrip
           Evita que se quiten los espacios alrededor de las cadenas
           extraídas.

       wrap
           Canoniza las cadenas a traducir, considerando que los espacios en
           blanco no son importantes, y justifica el documento traducido.
           Tienen preferencia sobre esta, las opciones personalizadas de cada
           tag. Consulte la opción "tags" de más abajo.

       caseinsensitive
           Realiza las búsquedas de tags y atributos sin tener en cuenta
           mayúsculas y minúsculas. Si está definido, tratará <BooK>laNG y
           <BOOK>Lang como <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 intentará encajar con la primera línea del doctype del
           documento (si está definida). Si no encaja, se considerará que el
           documento es de un tipo equivocado.

       tags
           Lista separada por espacios de los tags que desea traducir o
           omitir. Por defecto, los tags especificados serán excluidos, pero
           si utiliza la opción "tagsonly", los tags especificados serán los
           únicos incluidos. Los tags deben estar en la forma <aaa>, pero
           puede juntar algunos (<bbb><aaa>) para indicar que el contenido del
           tag <aaa> sólo se debe traducir cuando esté dentro del tag <bbb>.

           También puede especificar algunas opciones de tags poniendo algunos
           caracteres delante de la jerarquía de tags. Por ejemplo, puede
           poner ’w’ (justificar) o ’W’ (no justificar) para hacer caso omiso
           del comportamiento por defecto especificaco por la opción global
           "wrap".

           Ejemplo: W<chapter><title>

       attributes
           Lista separada por espacios de los atributos de tags que quiere
           traducir. Puede especificar los atributos por su nombre (por
           ejemplo, "lang"), pero puede añadirle como prefijo una jerarquía de
           tags, para especificar que este tag sólo se debe traducir cuando
           esté dentro del tag especificado. Por ejemplo: <bbb><aaa>lang
           indica que el atributo lang sólo se traducirá cuando esté dentro
           del tag <aaa>, y este esté dentro de un tag <bbb>.

       inline
           Lista separada por espacios de los tags que quiere tratar como
           inline (que no rompen la secuencia).  Por defecto, todos los tags
           rompen la secuencia.  Sigue la misma sintaxis que la opción tags.

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

ESCRIBIENDO MODULOS DERIVADOS

       DEFINIR QUE TAGS Y ATRIBUTOS TRADUCIR

       La personalización más simple es definir qué tags y atributos quiere
       que el analizador traduzca. Esto se debe hacer en la función
       initialize.  Primero debe llamar a la inicialización principal, para
       obtener las opciones de línea de comandos, y luego, añadir sus
       definiciones personalizadas al hash de opciones.  Si quiere tratar
       nuevas opciones de la línea de comandos, debe definirlas antes de
       llamar a la función initialize principal:

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

       REDEFINIENDO LA FUNCION found_string

       Otro paso simple es redefinir la función "found_string", que recibe las
       cadenas extraídas por el analizador, para traducirlas.  Ahí puede
       controlar qué cadenas quiere traducir, y realizar pequeñas traducciones
       anyes o después de la traducción misma.

       Recibe el texto extraído, la referencia de dónde está, y un hash que
       contiene información extra para controlar qué cadenas traducir, cómo
       traducirlas y generar el comentario.

       El contenido de las opciones depende del tipo de cadena que sea
       (especificado en una entrada del hash):

       type="tag"
           La cadena encontrada es el contenido de un tag traducible. La
           entrada "tag_options" contiene los caracteres de opciones que
           hubiera delante de la jerarquía de tags en la opción "tags" del
           módulo.

       type="attribute"
           Significa que la cadena encontrada es el valor de un atributo
           traducible. La entrada "attribute" contiene el nombre del atributo.

       Debe devolver el texto que reemplazará al original en el documento
       traducido. Aquí hay un ejemplo básico de ésta función:

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

       Hay otro ejemplo simple en el nuevo módulo de Dia, que sólo filtra
       algunas cadenas.

       MODIFICANDO LOS TIPOS DE TAGS

       Esta personalización es más compleja, pero le permite (prácticamente)
       una personalización total.  Está basada en una lista de hashes, cada
       uno de los cuales define el comportamiento de un tipo de tags. La lista
       debe estar ordenada para que los tags más generales estén después de
       los más concretos (ordenado primero por la llave beginning y luego por
       la end). Para definir un tipo de tag debe construir un hash con las
       siguientes llaves:

       beginning
           Especifica el principio del tag, después del "<".

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

       breaking
           Indica si esta clase de tags rompe la secuencia.  Un tag no
           rompedor (inline) es uno que puede tomarse como parte del contenido
           de otro tag.  Puede tomar valores falso (0), cierto (1) o
           indefinido.  Si se deja indefinido, deeberá definir la función
           f_breaking que indicará si un tag concreto de esta clase es
           rompedor o no.

       f_breaking
           Es una función que dirá si el siguiente tag es rompedor o no.  Debe
           definirla si deja la opción "breaking" indefinida.

       f_extract
           Si deja esta llave indefinida, la función de extracción genérica
           deberá extraer el tag por si misma. Es interesante para tags que
           pueden que pueden contener otros tags o estructuras especiales
           dentro, y que puedeen confundir al analizador principal.  Esta
           función recibe un booleano que indica si el tag se debe eliminar
           del documento de entrada o no.

       f_translate
           Esta función devuelve el tag (en el formato de get_string_until())
           y devuelve el tag traducido (atributos y toda la información
           necesaria traducidos) como una única cadena.

FUNCIONES INTERNAS utilizadas para escribir analizadores derivados

       TRABAJANDO CON TAGS

       get_path()
           Esta función devuelve la ruta hasta el tag actual desde la raíz del
           documento, de la forma <html><body><p>.

       tag_type()
           Esta función devuelve el índice de la lista tag_types que encaja
           con el siguiente tag en el documento de entrada, o -1 si se está al
           final del fichero.

       extract_tag($$)
           Esta función devuelve el próximo tag del documento de entrada sin
           el principio ni el final, en forma de array, para mantener las
           referencias del fichero de entrada. Tiene dos parámetros: el tipo
           del tag (tal como devuelve tag_type) y un booleano, que indica si
           se debe eliminar del fichero de entrada.

       get_tag_name(@)
           Esta función devuelve el nombre del tag pasado como parámetro, en
           la forma de array devuelta por extract_tag.

       breaking_tag()
           Esta función devuelve un booleano que indica si el siguiente tag
           del documento de entrada es un tag "rompedor" o no (es un tag
           inline).  Esto deja el documento de entrada intacto.

       treat_tag()
           Esta función traduce el siguiente tag del documento de entrada.
           Usa las funciones de traducción personalizadas de cada tipo de tag.

       tag_in_list($@)
           Esta función devuelve una cadena que dice si el primer parámetro
           (una gerarquía de tags) encaja con alguno de los tags del segundo
           parámetro (una lista de tags o jerarquías de tags). Si no encaja,
           devuelve 0. Sinó, devuelve las opciones del tag encajado (los
           caracteres delante del tag) o 1 (si el tag no tiene opciones).

       TRABAJANDO CON ATRIBUTOS

       treat_attributes(@)
           Esta función trata la traducción de los atributos de los tags.
           Recibe un tag sin las marcas de principio / final, y luego busca
           los atributos, y traduce los traducibles (especificados por la
           opción "attributes" del módulo).  Devuelve una cadena con el tag
           traducido.

       TRABAJANDO CON LAS OPCIONES DEL MODULO

       treat_options()
           Esta función llena las estructuras internas que contienen los datos
           tags, atributos e "inline" con las opciones del módulo
           (especificadas en la línea de comandos o en la función de
           inicialización).

       OBTENIENDO EL TEXTO DEL DOCUMENTO DE ENTRADA

       get_string_until($%)
           Esta función devuelve una lista con las lineas (y referencias) del
           documento de entrada hasta que encuentra el primer parámetro.  El
           segundo parámetro es un hash de opciones. El valor 0 significa
           desactivado (por defecto) y 1, activado.

           Las opciones válidas son:

           include
               Esto hace que el array de retorno contenga la cadena buscada

           remove
               Esto elimina de la entrada la cadena

           unquoted
               Esto asegura que el texto buscado se encuentra fuera de
               fragmentos encomillados

       skip_spaces(\@)
           Esta función recibe como parámetro la referencia a un párrafo (en
           el formato devuelto por get_string_until), salta los espacios del
           principio y los devuelve como una cadena simple.

       join_lines(@)
           Esta función devuelve una simple cadena con el texto del array del
           parámetro (descartando las referencias).

ESTADO DE ESTE MODULO

       Este módulo puede traducir tags y atributos.

       El soporte para entidades y inclusión de ficheros está en la lista de
       tareas pendientes.

       La escritura de módulos derivados es aún muy limitada.

LISTA DE TAREAS PENDIENTES

       DOCTYPE (ENTIDADES)

       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.

       FICHEROS INCLUIDOS

       "MODIFICAR LOS TIPOS DE TAGS DESDE LOS MODULOS HERENCIADOS (mover la
       estructura tag_types dentro del hash $self?)

       un tag rompedor dentro de un tag no-rompedor (posible?) provoca
       comentarios muy feos

VER TAMBIEN

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

AUTORES

        Jordi Vilalta <jvprat@gmail.com>

TRADUCCION

        Jordi Vilalta <jvprat@gmail.com>

DERECHO DE COPIA Y LICENCIA

       Copyright (c) 2004 por Jordi Vilalta <jvprat@gmail.com>

       Esto es software libre; puedes redistribuirlo y/o modificarlo bajo las
       condiciones de la GPL (ver el archivo COPYING).