Provided by: po4a_0.41-1ubuntu1_all bug

NOMBRE

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

DESCRIPCI'ON

       El objetivo del proyecto po4a (<<PO for anything>>, PO para todo) es
       facilitar la traduccion (y mas interesante, el mantenimiento de las
       traducciones) usando las herramientas de gettext en areas donde no eran
       de esperar, como la documentacion.

       Locale::Po4a::Xml es un modulo que asiste en la traduccion de
       documentacion en el formato XML a otros lenguajes (humanos). Tambien se
       puede usar como base para construir modulos para documentos basados en
       XML.

TRADUCIR CON PO4A::XML

       Este modulo se puede usar directamente para tratar documentos XML
       genericos. Extraera el contenido de todas las etiquetas, y ningun
       atributo, ya que ahi es donde se escribe el texto en la mayoria de
       documentos basados en XML.

       Hay algunas opciones (descritas en la siguiente seccion) que pueden
       personalizar este comportamiento. Si eso no es suficiente para el
       formato de su documento, le animo a que escriba su propio modulo
       derivado de este para describir los detalles de su formato. Consulte la
       seccion Escribir m'odulos derivados que encontrara mas abajo para una
       descripcion del proceso.

OPCIONES ACEPTADAS POR ESTE MODULO

       La opcion <<debug>> global provoca que este modulo muestre las cadenas
       excluidas, para ver si se salta algo importante.

       Estas son las opciones particulares de este modulo:

       nostrip
           Evita que se quiten los espacios alrededor de las cadenas
           extraidas.

       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
           etiqueta. Consulte la opcion <<tags>> mas abajo.

       caseinsensitive
           Permite que las busquedas de etiqueta y atributos no tengan en
           cuenta mayusculas y minusculas. Si esta definido, tratara
           <BooK>laNG y <BOOK>Lang como <book>lang.

       includeexternal
           Si se define, se incluiran las entidades externas en el documento
           (traducido) generado, asi como para la extraccion de cadenas. De no
           estar definido tendra que traducir las entidades externas
           separadamente, como documentos independientes.

       ontagerror
           Esta opcion define el comportamiento del modulo cuando encuentra
           una sintaxis XML no valida (una etiqueta de cierre que no concuerda
           con la ultima etiqueta de inicio, o un atributo de etiqueta sin un
           valor). Puede tomar los siguientes valores.

           fail
               Este es el valor predefinido. El modulo cerrara con un mensaje
               de error.

           warn
               El modulo continuara, mostrando una advertencia.

           silent
               El modulo continuara sin advertencias.

           Sea cuidadoso a la hora de usar esta opcion. En general,
           recomendamos arreglar el fichero de entrada.

       tagsonly
           Extrae unicamente las etiquetas especificadas en la opcion
           <<tags>>. De no ser asi, extraera todas las etiquetas excepto las
           especificadas.

           Nota: Esta opcion esta obsoleta.

       doctype
           La cadena que intentara encajar con la primera linea del
           <<doctype>> del documento (si esta definida). Una advertencia
           indicara que el documento puede ser de un tipo equivocado, si no
           encaja.

       addlang
           Cadena que indica la ruta (por ejemplo, <bbb><aaa>) de una etiqueta
           donde se ha de anadir el atributo <<lang="...">>. El idioma se
           definira como el nombre base del fichero PO sin ninguna extension
           <<po>>.

       tags
           Lista separada por espacios de las etiquetas que desea traducir u
           omitir. Por omision, se excluiran las etiquetas especificadas, pero
           si utiliza la opcion <<tagsonly>>, las etiquetas especificadas
           seran los unicos incluidos. Las etiquetas deben tener la forma
           <aaa>, pero puede juntar algunos (<bbb><aaa>) para indicar que el
           contenido de la etiqueta <aaa> solo se debe traducir cuando este
           dentro de la etiqueta <bbb>.

           Tambien puede especificar algunas opciones de etiqueta poniendo
           algunos caracteres delante de la jerarquia de etiquetas. Por
           ejemplo, puede poner <<w>> (justificar) o <<W>> (no justificar)
           para hacer caso omiso del comportamiento predefinido especificado
           por la opcion global <<wrap>>.

           Ejemplo: W<chapter><title>

           Nota: Esta opcion esta obsoleta. En lugar de ello, deberia usar las
           opciones translated y untranslated.

       attributes
           Lista separada por espacios de los atributos de etiquetas que
           quiere traducir. Puede especificar los atributos por su nombre (por
           ejemplo, <<lang>>), pero puede anadirle como prefijo una jerarquia
           de etiquetas para especificar que esta etiqueta solo se debe
           traducir cuando este dentro de la etiqueta especificada. Por
           ejemplo: <bbb><aaa>lang indica que el atributo <<lang>> solo se
           traducira cuando este dentro de la etiqueta <aaa>, y esta este
           dentro de una etiqueta <bbb>.

       foldattributes
           No traduce los atributos en etiquetas en linea. En lugar de ello,
           reemplaza todos los atributos de una etiqueta con po4a-id=<id>.

           Esto es util cuando no se deben traducir los atributos,
           simplificando las cadenas a las traductores evitando asi errores al
           teclear.

       customtag
           Lista separada por espacios de las etiquetas que no se deberian
           tratar como tales. Estas se tratan como etiquetas en linea, y no
           precisan cierre.

       break
           Lista separada por espacios de las etiquetas que deberian romper la
           secuencia. Por omision todas las etiquetas rompen la secuencia.

           Las etiquetas deben tener la forma <aaa>, pero puede unir algunas
           (<bbb><aaa>), si una etiqueta (<aaa>) solo se debe considerar
           cuando esta dentro de otra etiqueta.

       inline
           Lista separada por espacios de las etiquetas que quiere tratar como
           elementos en linea (que no rompen la secuencia). Por omision todas
           las etiquetas rompen la secuencia.

           Las etiquetas deben tener la forma <aaa>, pero puede unir algunas
           (<bbb><aaa>), si una etiqueta (<aaa>) solo se debe considerar
           cuando esta dentro de otra etiqueta.

       placeholder
           Lista separada por espacios de las etiquetas que se deberian tratar
           como marcadores de posicion (<<placeholders>>). Estos no rompen la
           secuencia, pero su contenido se traduce separadamente.

           La ubicacion del <<placeholder>> dentro de su bloque se marcara con
           una cadena similar a:

             <placeholder type=\"footnote\" id=\"0\"/>

           Las etiquetas deben tener la forma <aaa>, pero puede unir algunas
           (<bbb><aaa>), si una etiqueta (<aaa>) solo se debe considerar
           cuando esta dentro de otra etiqueta.

       nodefault
           Una lista separada por espacios de etiquetas que el modulo no
           deberia definir en ninguna categoria de manera predefinidas.

       cpp Compatibilidad con directivas de preprocesador de C. Si activa esta
           opcion, po4a tratara las directivas de preprocesador como
           separadores de parrafo. Esto cobra importancia si se debe
           preprocesar el fichero XML, ya que de otra forma las directivas se
           podrian insertar en medio de la linea si po4a considera que
           pertenecen al parrafo actual, y serian irreconocibles para el
           preprocesador. Nota: las directivas del preprocesador deben
           aparecer entre etiquetas (no deben romper etiquetas).

       translated
           Una lista separada por espacios de etiquetas que desea traducir.

           Las etiquetas deben tener la forma <aaa>, pero puede unir algunas
           (<bbb><aaa>), si una etiqueta (<aaa>) solo se debe considerar
           cuando esta dentro de otra etiqueta.

           Tambien puede especificar algunas opciones de etiquetas poniendo
           algunos caracteres delante de la jerarquia de etiquetas. Por
           ejemplo, puede poner <<w>> (justificar) o <<W>> (no justificar)
           para hacer caso omiso del comportamiento predefinido especificado
           por la opcion global <<wrap>>.

           Ejemplo: W<chapter><title>

       untranslated
           Lista separada por espacios de las etiquetas que no desea traducir.

           Las etiquetas deben tener la forma <aaa>, pero puede unir algunas
           (<bbb><aaa>), si una etiqueta (<aaa>) solo se debe considerar
           cuando esta dentro de otra etiqueta.

       defaulttranslateoption
           Las categorias predefinidas para las etiquetas que no pertenecen a
           translated, untranslated, break, inline, o placeholder.

           Este es un conjunto de letras:

           w   Las etiquetas deberian traducirse, y se puede justificar el
               contenido.

           W   Las etiquetas deberian traducirse, y no se debe justificar el
               contenido.

           i   Las etiquetas se deberian traducir como elementos en linea.

           p   Las etiquetas se deberian traducir como marcadores de posicion.

ESCRIBIR M'ODULOS DERIVADOS

   DEFINIR QU'E ETIQUETAS Y ATRIBUTOS TRADUCIR
       La personalizacion mas simple es definir que etiquetas (<<tags>>) y
       atributos quiere que el analizador traduzca. Esto se debe hacer en la
       funcion <<initialize>>. Primero debe invocar la inicializacion
       principal, para obtener las opciones de la linea de ordenes, y luego,
       anadir sus definiciones personalizadas a la tabla <<hash>> de opciones.
       Si quiere tratar nuevas opciones de la linea de ordenes, debe
       definirlas antes de invocar la funcion <<initialize>> principal:

         $self->{options}{'new_option'}='';
         $self->SUPER::initialize(%options);
         $self->{options}{'_default_translated'}.=' <p> <head><title>';
         $self->{options}{'attributes'}.=' <p>lang id';
         $self->{options}{'_default_inline'}.=' <br>';
         $self->treat_options;

       Deberia usar las opciones _default_inline, _default_break,
       _default_placeholder, _default_translated, _default_untranslated y
       _default_attributes con modulos derivados. Esto permite a los usuarios
       invalidar el comportamiento predefinido configurado en su modulo
       mediante las opciones de linea de ordenes.

   REDEFINIR LA FUNCI'ON found_string
       Otro paso simple es redefinir la funcion <<found_string>>, que recibe
       las cadenas extraidas por el analizador para su traduccion. Ahi puede
       controlar que cadenas quiere traducir, y realizar pequenas
       transformaciones antes o despues de la traduccion misma.

       Recibe el texto extraido, la referencia de donde esta, y una tabla
       <<hash>> que contiene informacion adicional para controlar que cadenas
       traducir, como traducirlas y generar el comentario.

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

       type="etiqueta"
           La cadena encontrada es el contenido de una etiqueta (<<tag>>)
           traducible. La entrada <<tag_options>> (opciones de etiquetas)
           contiene los caracteres de opciones delante de la jerarquia de
           etiquetas en la opcion <<tags>> del modulo.

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

       Debe devolver el texto que reemplazara al original en el documento
       traducido. Aqui hay un ejemplo basico de esta funcion:

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

       Aqui tiene otro ejemplo simple en el nuevo modulo Dia, que solo filtra
       algunas cadenas.

   MODIFICAR LOS TIPOS DE ETIQUETA (PENDIENTE)
       Esta personalizacion es mas compleja, pero le permite una
       personalizacion (practicamente) total. Esta basada en una lista de
       tablas de elementos asociativos (<<hash>>), cada una de las cuales
       define el comportamiento de un tipo de etiqueta. La lista debe estar
       ordenada para que las etiquetas mas generales esten despues de las mas
       concretas (ordenado primero por la llave <<beginning>> y luego por la
       llave <<end>>). Para definir un tipo de etiqueta debe construir un
       <<hash>> con las siguientes llaves:

       beginning
           Especifica el principio de la etiqueta, despues de <<<>>.

       end Especifica el final de la etiqueta, antes de <<>>>.

       breaking
           Indica si esta clase de etiqueta rompe la secuencia. Una etiqueta
           en linea (<<inline>>) que no rompe la secuencia es uno que se puede
           tomar como parte del contenido de otra etiqueta. Puede tomar los
           valores falso (0), verdadero (1) o indefinido. Si se deja
           indefinido, debera definir la funcion <<f_breaking>>, que indicara
           si una etiqueta de esta clase en concreto rompe o no la secuencia.

       f_breaking
           Es una funcion que dira si la siguiente etiqueta rompe o no. Debe
           definirla si la opcion breaking no lo esta.

       f_extract
           Si deja esta llave indefinida, la funcion de extraccion generica
           debera extraer la etiqueta por si misma. Es util con etiquetas que
           pueden contener otras etiquetas o estructuras especiales dentro, y
           que pueden confundir al analizador principal. Esta funcion recibe
           un booleano que indica si la etiqueta se debe eliminar del
           documento de entrada o no.

       f_translate
           Esta funcion devuelve la etiqueta (en el formato
           <<get_string_until()>>) y devuelve la etiqueta traducida (atributos
           y toda la informacion necesaria traducidos) como una unica cadena.

FUNCIONES INTERNAS utilizadas para escribir analizadores derivados

   TRABAJAR CON ETIQUETAS
       get_path()
           Esta funcion devuelve la ruta hasta la etiqueta actual desde la
           raiz del documento, con la forma <html><body><p>.

           Puede introducir como argumento una lista adicional de etiquetas
           (sin corchetes). Estos elementos de ruta se anaden la final de la
           ruta actual.

       tag_type()
           Esta funcion devuelve el indice de la lista <<tag_types>> que
           encaja con la siguiente etiqueta en el documento de entrada, o
           <<-1>> si esta al final del fichero.

       extract_tag($$)
           Esta funcion devuelve la proxima etiqueta del documento de entrada
           sin el principio ni el final, en forma de vector (<<array>>), para
           mantener las referencias del fichero de entrada. Tiene dos
           parametros: el tipo de la etiqueta (tal como devuelve <<tag_type>>)
           y un booleano, que indica si se debe eliminar del fichero de
           entrada.

       get_tag_name(@)
           Esta funcion devuelve el nombre de la etiqueta introducida como
           argumento, en la forma de vector devuelta por <<extract_tag>>.

       breaking_tag()
           Esta funcion devuelve un booleano que indica si la siguiente
           etiqueta del documento de entrada es una etiqueta que rompe o no
           (es una etiqueta en linea). Esto deja el documento de entrada
           intacto.

       treat_tag()
           Esta funcion traduce la siguiente etiqueta del documento de
           entrada. Usa las funciones de traduccion personalizadas de cada
           tipo de etiqueta.

       tag_in_list($@)
           Esta funcion devuelve una cadena que dice si el primer argumento
           (una jerarquia de etiquetas) encaja con alguna de las etiquetas del
           segundo argumento (una lista de etiquetas o jerarquias de
           etiqueta). Si no encaja, devuelve cero. De otra forma, devuelve las
           opciones de la etiqueta emparejada (los caracteres delante de la
           etiqueta) o 1 (si la etiqueta no tiene opciones).

   TRABAJAR CON ATRIBUTOS
       treat_attributes(@)
           Esta funcion trata la traduccion de los atributos de las etiquetas.
           Recibe una etiqueta sin las marcas beginning / end, y luego busca
           los atributos y traduce los traducibles (especificados con la
           opcion <<attributes>> del modulo). Devuelve una cadena con la
           etiqueta traducido.

   TRABAJAR CON LAS OPCIONES DEL M'ODULO
       treat_options()
           Esta funcion llena las estructuras internas que contienen las
           etiquetas, atributos y datos de elementos en linea con las opciones
           del modulo (especificadas en la linea de ordenes o en la funcion
           <<initialize>>).

   OBTENER TEXTO DEL DOCUMENTO DE ENTRADA
       get_string_until($%)
           Esta funcion devuelve una lista con las lineas (y referencias) del
           documento de entrada hasta que encuentra el primer argumento. El
           segundo argumento es una tabla <<hash>> de opciones. El valor de
           cero significa desactivado (valor predefinido) y 1, activado.

           Las opciones validas son:

           include
               Esto hace que la lista de retorno contenga la cadena buscada.

           remove
               Esto elimina el flujo devuelto de la entrada.

           unquoted
               Esto asegura que el texto buscado se encuentra fuera de cadenas
               entrecomilladas.

       skip_spaces(\@)
           Esta funcion recibe como argumento la referencia a un parrafo (en
           el formato devuelto por <<get_string_until>>), omite los espacios
           de la cabecera y los devuelve como una cadena simple.

       join_lines(@)
           Esta funcion devuelve una cadena simple con el texto de la lista
           del argumento (descartando las referencias).

ESTADO DE ESTE MODULO

       Este modulo puede traducir etiquetas y atributos.

LISTA DE TAREAS PENDIENTES

       DOCTYPE (ENTIDADES)

       Existe una minima compatibilidad con la traduccion de entidades. Se
       traducen en conjunto, y no se tienen en cuenta las etiquetas. Las
       entidades multi-linea no son compatibles y siempre se justifican las
       entidades durante la traduccion.

       MODIFICAR LOS TIPOS DE ETIQUETA DE LOS MODULOS HEREDADOS (cmover la
       estructura <<tag_types>> dentro de la tabla hash $self?)

V'EASE TAMBI'EN

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

AUTORES

        Jordi Vilalta <jvprat@gmail.com>
        Nicolas Francois <nicolas.francois@centraliens.net>

DERECHO DE COPIA Y LICENCIA

        Copyright (c) 2004 por Jordi Vilalta  <jvprat@gmail.com>
        Copyright (c) 2008-2009 por Nicolas Francois <nicolas.francois@centraliens.net>

       Esto es software libre; puede redistribuirlo y/o modificarlo bajo las
       condiciones de la licencia GPL (consulte el fichero COPYING).