Provided by: po4a_0.34-2_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
       traducciA~Xn (y mA~Xs interesante, el mantenimiento de las
       traducciones) usando las herramientas de gettext en A~Xreas dA~Xnde no
       eran de esperar, como en la documentaciA~Xn.

       Locale::Po4a::Xml es un mA~Xdulo para ayudar en la traducciA~Xn de
       documentaciA~Xn en el formato XML a otros lenguajes [humanos].
       TambiA~Xn se puede usar como base para construir mA~Xdulos para
       documentos basados en XML.

TRADUCIENDO CON PO4A::XML

       Este mA~Xdulo puede usarse directamente para tratar documentos XML
       genA~Xricos. Esto extraerA~X el contenido de todos los tags, y ningA~Xn
       atributo, ya que ahA~ es donde se escribe el texto en la mayorA~a de
       documentos basados en XML.

       Hay algunas opciones (descritas en la siguiente secciA~Xn) que pueden
       personalizar este comportamiento. Si eso no es suficiente para su
       formato de documento, le animo a que escriba su propio mA~Xdulo
       derivado de A~Xste, para describir los detalles de su formato. Consulte
       la secciA~Xn "Escribiendo mA~Xdulos derivados" de mA~Xs abajo, para una
       descripciA~Xn del proceso.

OPCIONES ACEPTADAS POR ESTE MODULO

       La opciA~Xn debug global provoca que este mA~Xdulo muestre las cadenas
       excluidas, para ver si se salta algo importante.

       Estas son las opciones particulares de este mA~Xdulo:

       nostrip
           Evita que se quiten los espacios alrededor de las cadenas extraA~‐
           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 opciA~Xn "tags" de mA~Xs abajo.

       caseinsensitive
           Realiza las bA~Xsquedas de tags y atributos sin tener en cuenta
           mayA~Xsculas y minA~Xsculas. Si estA~X definido, tratarA~X
           <BooK>laNG y <BOOK>Lang como <book>lang.

       includeexternal
           When defined, external entities are included in the generated
           (translated) document, and for the extraction of strings.  If it’s
           not defined, you will have to translate external entities
           separately as independent documents.

       ontagerror
           This option defines the behavior of the module when it encounter a
           invalid Xml syntax (a closing tag which does not match the last
           opening tag, or a tag’s attribute without value).  It can take the
           following values:

           fail
               This is the default value.  The module will exit with an error.

           warn
               The module will continue, and will issue a warning.

           silent
               The module will continue without any warnings.

           Be careful when using this option.  It is generally recommended to
           fix the input file.

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

           Note: This option is deprecated.

       doctype
           Cadena que intentarA~X encajar con la primera lA~nea del doctype
           del documento (si estA~X definida). Si no encaja, se considerarA~X
           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 serA~Xn excluidos, pero
           si utiliza la opciA~Xn "tagsonly", los tags especificados serA~Xn
           los A~Xnicos incluidos. Los tags deben estar en la forma <aaa>,
           pero puede juntar algunos (<bbb><aaa>) para indicar que el
           contenido del tag <aaa> sA~Xlo se debe traducir cuando estA~X
           dentro del tag <bbb>.

           TambiA~Xn puede especificar algunas opciones de tags poniendo
           algunos caracteres delante de la jerarquA~a de tags. Por ejemplo,
           puede poner ’w’ (justificar) o ’W’ (no justificar) para hacer caso
           omiso del comportamiento por defecto especificaco por la opciA~Xn
           global "wrap".

           Ejemplo: W<chapter><title>

           Note: This option is deprecated.  You should use the translated and
           untranslate options instead.

       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 aA~Xadirle como prefijo una jerarquA~a
           de tags, para especificar que este tag sA~Xlo se debe traducir
           cuando estA~X dentro del tag especificado. Por ejemplo:
           <bbb><aaa>lang indica que el atributo lang sA~Xlo se traducirA~X
           cuando estA~X dentro del tag <aaa>, y este estA~X 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 opciA~Xn tags.

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

       cpp Support C preprocessor directives.  When this option is set, po4a
           will consider preprocessor directives as paragraph separators.
           This is important if the XML file must be preprocessed because
           otherwise the directives may be inserted in the middle of lines if
           po4a consider it belong to the current paragraph, and they won’t be
           recognized by the preprocessor.  Note: the preprocessor directives
           must only appear between tags (they must not break a tag).

       translated
       unstranslated
           Space-separated list of the tags you want to translate or not.  The
           tags must be in the form <aaa>, but you can join some (<bbb><aaa>)
           to indicate that the content of the tag <aaa> will only be
           translated when itaXXs into a <bbb> tag.

           You can also specify some tag options putting some characters in
           front of the tag hierarchy. For example, you can put aXXwaXX (wrap)
           or aXXWaXX (donaXXt wrap) to overide the default behavior specified
           by the global "wrap" option.

           Ejemplo: W<chapter><title>

ESCRIBIENDO MODULOS DERIVADOS

   DEFINIR QUE TAGS Y ATRIBUTOS TRADUCIR
       La personalizaciA~Xn mA~Xs simple es definir quA~X tags y atributos
       quiere que el analizador traduzca. Esto se debe hacer en la funciA~Xn
       initialize.  Primero debe llamar a la inicializaciA~Xn principal, para
       obtener las opciones de lA~nea de comandos, y luego, aA~Xadir sus
       definiciones personalizadas al hash de opciones.  Si quiere tratar
       nuevas opciones de la lA~nea de comandos, debe definirlas antes de
       llamar a la funciA~Xn 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 funciA~Xn "found_string", que recibe
       las cadenas extraA~das por el analizador, para traducirlas.  AhA~ puede
       controlar quA~X cadenas quiere traducir, y realizar pequeA~Xas
       traducciones anyes o despuA~Xs de la traducciA~Xn misma.

       Recibe el texto extraA~do, la referencia de dA~Xnde estA~X, y un hash
       que contiene informaciA~Xn extra para controlar quA~X cadenas traducir,
       cA~Xmo 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 jerarquA~a de tags en la opciA~Xn "tags" del
           mA~Xdulo.

       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 reemplazarA~X al original en el documento
       traducido. AquA~ hay un ejemplo bA~Xsico de A~Xsta funciA~Xn:

         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 mA~Xdulo de Dia, que sA~Xlo filtra
       algunas cadenas.

   MODIFICANDO LOS TIPOS DE TAGS
       Esta personalizaciA~Xn es mA~Xs compleja, pero le permite
       (prA~Xcticamente) una personalizaciA~Xn total.  EstA~X 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 mA~Xs
       generales estA~Xn despuA~Xs de los mA~Xs 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, despuA~Xs 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, deeberA~X definir la funciA~Xn
           f_breaking que indicarA~X si un tag concreto de esta clase es
           rompedor o no.

       f_breaking
           Es una funciA~Xn que dirA~X si el siguiente tag es rompedor o no.
           Debe definirla si deja la opciA~Xn "breaking" indefinida.

       f_extract
           Si deja esta llave indefinida, la funciA~Xn de extracciA~Xn
           genA~Xrica deberA~X 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 funciA~Xn recibe un booleano que indica si el tag se debe
           eliminar del documento de entrada o no.

       f_translate
           Esta funciA~Xn devuelve el tag (en el formato de
           get_string_until()) y devuelve el tag traducido (atributos y toda
           la informaciA~Xn necesaria traducidos) como una A~Xnica cadena.

FUNCIONES INTERNAS utilizadas para escribir analizadores derivados

   TRABAJANDO CON TAGS
       get_path()
           Esta funciA~Xn devuelve la ruta hasta el tag actual desde la raA~z
           del documento, de la forma <html><body><p>.

       tag_type()
           Esta funciA~Xn devuelve el A~ndice de la lista tag_types que encaja
           con el siguiente tag en el documento de entrada, o -1 si se estA~X
           al final del fichero.

       extract_tag($$)
           Esta funciA~Xn devuelve el prA~Xximo 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 parA~Xmetros: 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 funciA~Xn devuelve el nombre del tag pasado como parA~Xmetro,
           en la forma de array devuelta por extract_tag.

       breaking_tag()
           Esta funciA~Xn 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 funciA~Xn traduce el siguiente tag del documento de entrada.
           Usa las funciones de traducciA~Xn personalizadas de cada tipo de
           tag.

       tag_in_list($@)
           Esta funciA~Xn devuelve una cadena que dice si el primer
           parA~Xmetro (una gerarquA~a de tags) encaja con alguno de los tags
           del segundo parA~Xmetro (una lista de tags o jerarquA~as de tags).
           Si no encaja, devuelve 0. SinA~X, 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 funciA~Xn trata la traducciA~Xn 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
           opciA~Xn "attributes" del mA~Xdulo).  Devuelve una cadena con el
           tag traducido.

   TRABAJANDO CON LAS OPCIONES DEL MODULO
       treat_options()
           Esta funciA~Xn llena las estructuras internas que contienen los
           datos tags, atributos e "inline" con las opciones del mA~Xdulo
           (especificadas en la lA~nea de comandos o en la funciA~Xn de
           inicializaciA~Xn).

   OBTENIENDO EL TEXTO DEL DOCUMENTO DE ENTRADA
       get_string_until($%)
           Esta funciA~Xn devuelve una lista con las lineas (y referencias)
           del documento de entrada hasta que encuentra el primer parA~Xmetro.
           El segundo parA~Xmetro es un hash de opciones. El valor 0 significa
           desactivado (por defecto) y 1, activado.

           Las opciones vA~Xlidas 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 funciA~Xn recibe como parA~Xmetro la referencia a un pA~Xrrafo
           (en el formato devuelto por get_string_until), salta los espacios
           del principio y los devuelve como una cadena simple.

       join_lines(@)
           Esta funciA~Xn devuelve una simple cadena con el texto del array
           del parA~Xmetro (descartando las referencias).

ESTADO DE ESTE MODULO

       Este mA~Xdulo puede traducir tags y atributos.

       El soporte para entidades y inclusiA~Xn de ficheros estA~X en la lista
       de tareas pendientes.

       La escritura de mA~Xdulos derivados es aA~Xn 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).