Provided by: po4a_0.41-1ubuntu1_all bug

NOMBRE

       Locale::Po4a::TeX - Convierte de documentos TeX 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::TeX es un modulo que asiste en la traduccion de
       documentos TeX a otros lenguajes (humanos). Tambien se puede usar como
       base para construir modulos para documentos basados en TeX.

       Probablemente, los usuarios deberian usar el modulo LaTeX, que hereda
       del modulo TeX y contiene las definiciones de las ordenes mas comunes
       de LaTeX.

TRADUCIR CON PO4A::TEX

       Este modulo se puede usar directamente para tratar documentos TeX
       genericos. Esto dividira el documento en bloques mas pequenos
       (parrafos, bloques literales, o incluso mas pequenos, como titulos o
       indices).

       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.

       Este modulo se puede personalizar con lineas que empiecen con <<%
       po4a:>> en el fichero TeX. Esta personalizacion se describe en la
       seccion PERSONALIZACI'ON DE OBJETOS EN L'INEA.

OPCIONES ACEPTADAS POR ESTE MODULO

       Estas son las opciones particulares de este modulo:

       debug
           Activa la depuracion de fallos para algunos mecanismos internos del
           modulo. Use el codigo fuente para ver que partes se pueden depurar.

       no_wrap
           Lista separada por comas de los entornos que no se deben
           justificar.

           Tenga en cuenta que los entornos literales (verbatim) y no_wrap son
           diferentes. En los bloques literales no se analizan las ordenes ni
           los comentarios.

           Si este entorno no se registro ya, po4a considerara que este
           entorno no acepta ningun argumento.

       exclude_include
           Lista separada por dos puntos de los ficheros que no se deben
           incluir mediante <<\input>> e <<\include>>.

       definitions
           El nombre de un fichero que contiene definiciones para po4a, tal y
           como se define en la seccion PERSONALIZACI'ON DE OBJETOS EN L'INEA.
           Puede usar esta opcion si no es posible introducir definiciones en
           el documento que esta traduciendo.

       verbatim
           Lista separada por comas de los entornos que no se deben
           justificar.

           Si este entorno no se registro ya, po4a considerara que este
           entorno no acepta ningun argumento.

       Utilizar estas opciones puede modificar el comportamiento de las
       ordenes definidas en las listas predefinidas.

PERSONALIZACI'ON DE OBJETOS EN L'INEA

       El modulo TeX se puede personalizar mediante lineas que empiecen con %
       po4a:. Estas lineas se interpretan como ordenes para el analizador. Se
       reconocen las siguientes ordenes:

       % po4a: command orden1 alias orden2
           Indica que los argumentos de la orden orden1 se deben tratar como
           los argumentos de la orden orden2.

       % po4a: command orden1 par'ametros
           Esto permite describir en detalle los parametros de la orden
           orden1. Esta informacion se usara para revisar el numero de
           argumentos y su tipo.

           Puede preceder la orden orden1 con

           un asterisco (*)
               po4a extraera esta orden de los parrafos (si esta ubicada al
               principio o final de un parrafo). Los traductores tendran que
               traducir los argumentos marcados como traducibles.

           un signo de suma (+)
               En cuanto al asterisco, la orden se extraera en caso de
               aparecer en el extremo de un bloque, pero los argumentos no se
               traduciran separadamente. El traductor tendra que traducir la
               orden unida a todos sus argumentos. Esto permite mantener un
               contexto mas completo, y es util con aquellas ordenes con
               pequenas palabras en sus argumentos, los cuales pueden tener
               varios significados (y traducciones).

               Nota: En este caso, no necesita especificar que argumentos son
               traducibles, pero po4a debe conocer el tipo y numero de
               argumentos.

           un signo de resta (-)
               En este caso, no se extraera la orden de ningun bloque. Pero si
               aparece solo en un bloque, solo los argumentos marcados como
               traducibles se entregaran al traductor. Esto es de utilidad
               para las ordenes de tipo de letra. Por lo general, estas
               ordenes no se deberian separar de su parrafo, (para mantener el
               contexto), pero no hay ninguna razon para molestar al traductor
               con ellas de aparecer una cadena completa dentro de una orden
               dada.

           El argumento par'ametros es un conjunto de [] (para indicar un
           argumento opcional) o {} (para indicar un argumento obligatorio).
           Puede colocar un subrayado (_) entre estos corchetes para indicar
           que el parametro se debe traducir. Por ejemplo:
            % po4a: orden *chapter [_] {_}

           Esto indica que la orden <<chapter>> tiene dos parametros: uno
           opcional (titulo corto) y uno obligatorio, los cuales se deben
           traducir.  Si desea especificar que la orden <<href>> tiene dos
           parametros obligatorios, que no quiere traducir la direccion URL
           (primer parametro), y que no quiere que se separe esta orden de su
           parrafo (lo cual permite al traductor desplazar el enlace en la
           oracion), puede usar:
            % po4a: command -href {}{_}

           En este caso, la informacion que indica que argumentos se deben
           traducir solo se emplea si un parrafo esta enteramente compuesto de
           la orden <<href>>.

       % po4a: environment entorno par'ametros
           Esto permite definir los parametros aceptados por el entorno
           entorno.  Esta informacion se emplea mas adelante para revisar el
           numero de argumentos de la orden <<\begin>>, y permite especificar
           cual se debe traducir.  La sintaxis del argumento par'ametros es la
           misma descrita para las ordenes.  El primer parametro de la orden
           <<\begin>> es el nombre del entorno.  No debe especificar este
           parametro en la lista de parametros. A continuacion tiene unos
           ejemplos:
            % po4a: environment multicols {}
            % po4a: environment equation

           La igual que con las ordenes, puede preceder entorno de un signo de
           suma (+) para indicar que la orden <<\begin>> se debe traducir con
           todos sus argumentos.

       % po4a: separator entorno "expresi'on_regular"
           Indica que un entorno se deberia dividir de acuerdo a la expresion
           regular dada.

           La expresion regular esta delimitada por comillas. No deberia crear
           ninguna referencia de apoyo. Deberia usar (?:) si necesita un
           grupo. Puede precisar tambien algunos escapes.

           Por ejemplo, el modulo LaTeX usa la expresion regular "(?:&|\\\\)"
           para traducir cada celula de la tabla por separado (las lineas
           separan con '\\' y las celulas con '&').

           La nocion de entorno depende del tipo mostrado en el fichero PO.
           Puede usar esto para dividirse con "\\\\" en el primer argumento
           obligatorio del nombre de la orden. En este caso, el entorno es
           <<title{#1}>>.

       % po4a: verbatim environment entorno
           Indica que entorno es un entorno literal. Los comentarios y ordenes
           se ignoraran en este entorno.

           Si este entorno no se registro ya, po4a considerara que este
           entorno no acepta ningun argumento.

ESCRIBIR M'ODULOS DERIVADOS

       pre_trans
       post_trans
       translate
           Un <<wrapper>> (envoltorio) al translate del Transtractor, con
           filtros de pre- y post-procesado.

           Los comentarios de un parrafo se insertan como comentarios del PO
           en la primera cadena traducida del parrafo.

       get_leading_command($buffer)
           Esta funcion devuelve:

           El nombre de la orden
               Si no se encuentra ninguna orden al principio del bufer dado,
               esta cadena estara vacia. Solo se consideran las ordenes que se
               pueden separar. La serie asociativa (hash)
               <<$separated_commands>> contiene la lista separada por espacios
               de estas ordenes.

           Una variante
               Indica si se utiliza una variante. Por ejemplo, se puede anadir
               un asterisco (*) al final de la orden de secciones para
               especificar que no se deben enumerar. En ese caso, este campo
               contendria "*". Si no hay ninguna variante, el campo contiene
               una cadena vacia.

           Una arreglo de tuplas (tipo de argumento, argumento)
               El tipo de argumento puede ser <<{>> (para argumentos
               obligatorios) o <<[>> (para argumentos opcionales).

           El resto del bufer
               El resto del bufer despues de la eliminacion de la orden
               inicial y sus parametros. Si no se encuentra ninguna orden, se
               devuelve a este campo el bufer original intacto.

       get_trailing_command($buffer)
           Lo mismo que get_leading_command, pero para las ordenes al final de
           la memoria intermedia.

       translate_buffer
           Traduce recursivamente una memoria intermedia separando de la misma
           la orden inicial y la final (los que se deben traducir por
           separado).

           Si una funcion se define en <<%translate_buffer_env>> para el
           entorno actual, esta funcion se usara para traducir el bufer en
           lugar de <<translate_buffer()>>.

       read
           Sobrecarga la lectura (<<read>>) de Transtractor

       read_file
           Lee un fichero recursivamente, anadiendo los ficheros incluidos que
           no estan listados en la lista <<@exclude_include>>. Los ficheros
           incluidos se buscan con la orden kpsewhich de la biblioteca
           Kpathsea.

           Exceptuando la parte de inclusion de ficheros, es una copia del
           <<read>> de Transtractor.

       parse_definition_file
           Subrutina para analizar un fichero con directivas po4a
           (definiciones de ordenes nuevas).

       parse_definition_line
           Analiza una linea de definicion con la forma <<% po4a: >>.

           Consulte la seccion PERSONALIZACI'ON DE OBJETOS EN L'INEA para mas
           detalles.

       is_closed
       docheader

FUNCIONES INTERNAS utilizadas para escribir analizadores derivados

       Las funciones de orden y entorno toman los siguientes argumentos
       (ademas del objeto <<$self>>):

       El nombre de la orden
       Una variante
       Una serie de tuplas (tipo, argumento)
       El entorno actual

       Los primeros 3 parametros se extraen con <<get_leading_command>> o
       <<get_trailing_command>>.

       Las funciones de orden y de entorno devuelven la traduccion de la orden
       con sus argumentos y un nuevo entorno.

       Las funciones de entorno se invocan cuando se encuentra una orden
       <<\begin>>. Se invocan con la orden <<\begin>> y sus argumentos.

       El modulo TeX solo propone una orden de funcion y una orden de entorno:
       <<generic_command>> y <<generic_environment>>.

       <<generic_command>> usa la informacion especificada por
       <<register_generic_command>>, o anadiendo una definicion para el
       fichero TeX:
        % po4a: command orden1 par'ametros <<generic_environment>> usa la
       informacion especificada por <<register_generic_environment>> o
       anadiendo una definicion al fichero de TeX:
        % po4a: environment entorno par'ametros

       Ambas funciones solo traducen los parametros especificados como
       traducibles (con una '_'). <<generic_environment>> afijara el nombre
       del entorno a la pila del entorno, y <<generic_command>> afijara el
       nombre de la orden seguida por un identificador del parametro (como
       {#7} o [#2]).

ESTADO DE ESTE MODULO

       Este modulo necesita mas pruebas.

       Se ha probado con un libro y con la documentacion de Python.

LISTA DE TAREAS PENDIENTES

       Deteccion automatica de ordenes nuevas
           El modulo TeX podria analizar los argumentos de la orden nueva e
           intentar determinar el numero de argumentos, su tipo y si se
           deberian traducir.

       Traduccion del separador de entorno
           Cuando usa <<\item>> como un separador de entorno, el elemento
           argumento se anade a la siguiente cadena.

       Algunas ordenes se deberian anadir a la pila (<<stack>>) del entorno
           Estas ordenes se deberian especificar por parejas. Esto permitiria
           especificar ordenes que inician o finalizan un entorno literal.

       Otros
           Hay varios puntos etiquetados con TODO en el codigo.

FALLOS CONOCIDOS

       Hay varios puntos etiquetados con FIXME en el codigo.

V'EASE TAMBI'EN

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

AUTORES

        Nicolas Francois <nicolas.francois@centraliens.net>

DERECHO DE COPIA Y LICENCIA

       Copyright 2004, 2005 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).