Provided by: po4a_0.41-1ubuntu1_all bug

NOMBRE

       Locale::Po4a::TeX - Convierte de documentos TeX y derivados desde/a
       ficheros PO

DESCRIPCIÓN

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

       Locale::Po4a::TeX es un módulo que asiste en la traducción de
       documentos TeX a otros lenguajes (humanos). También se puede usar como
       base para construir módulos para documentos basados en TeX.

       Probablemente, los usuarios deberían usar el módulo LaTeX, que hereda
       del módulo TeX y contiene las definiciones de las órdenes más comunes
       de LaTeX.

TRADUCIR CON PO4A::TEX

       Este módulo se puede usar directamente para tratar documentos TeX
       genéricos. Esto dividirá el documento en bloques más pequeños
       (párrafos, bloques literales, o incluso más pequeños, como títulos o
       índices).

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

       Este módulo se puede personalizar con lineas que empiecen con «% po4a:»
       en el fichero TeX. Esta personalización se describe en la sección
       PERSONALIZACIÓN DE OBJETOS EN LÍNEA.

OPCIONES ACEPTADAS POR ESTE MODULO

       Estas son las opciones particulares de este módulo:

       debug
           Activa la depuración de fallos para algunos mecanismos internos del
           módulo. Use el código fuente para ver qué 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 órdenes ni
           los comentarios.

           Si este entorno no se registró ya, po4a considerará que este
           entorno no acepta ningún 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 sección PERSONALIZACIÓN DE OBJETOS EN LÍNEA.
           Puede usar esta opción si no es posible introducir definiciones en
           el documento que está traduciendo.

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

           Si este entorno no se registró ya, po4a considerará que este
           entorno no acepta ningún argumento.

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

PERSONALIZACIÓN DE OBJETOS EN LÍNEA

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

       % 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 parmetros
           Esto permite describir en detalle los parámetros de la orden
           orden1. Esta información se usará para revisar el número de
           argumentos y su tipo.

           Puede preceder la orden orden1 con

           un asterisco (*)
               po4a extraerá esta orden de los párrafos (si está ubicada al
               principio o final de un párrafo). Los traductores tendrán que
               traducir los argumentos marcados como traducibles.

           un signo de suma (+)
               En cuanto al asterisco, la orden se extraerá en caso de
               aparecer en el extremo de un bloque, pero los argumentos no se
               traducirán separadamente. El traductor tendrá que traducir la
               orden unida a todos sus argumentos. Esto permite mantener un
               contexto más completo, y es útil con aquellas órdenes con
               pequeñas palabras en sus argumentos, los cuales pueden tener
               varios significados (y traducciones).

               Nota: En este caso, no necesita especificar qué argumentos son
               traducibles, pero po4a debe conocer el tipo y número de
               argumentos.

           un signo de resta (-)
               En este caso, no se extraerá la orden de ningún bloque. Pero si
               aparece solo en un bloque, sólo los argumentos marcados como
               traducibles se entregarán al traductor. Esto es de utilidad
               para las órdenes de tipo de letra. Por lo general, estas
               órdenes no se deberían separar de su párrafo, (para mantener el
               contexto), pero no hay ninguna razón para molestar al traductor
               con ellas de aparecer una cadena completa dentro de una orden
               dada.

           El argumento parmetros 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 parámetro se debe traducir. Por ejemplo:
            % po4a: orden *chapter [_] {_}

           Esto indica que la orden «chapter» tiene dos parámetros: uno
           opcional (título corto) y uno obligatorio, los cuales se deben
           traducir.  Si desea especificar que la orden «href» tiene dos
           parámetros obligatorios, que no quiere traducir la dirección URL
           (primer parámetro), y que no quiere que se separe esta orden de su
           párrafo (lo cual permite al traductor desplazar el enlace en la
           oración), puede usar:
            % po4a: command -href {}{_}

           En este caso, la información que indica qué argumentos se deben
           traducir sólo se emplea si un párrafo está enteramente compuesto de
           la orden «href».

       % po4a: environment entorno parmetros
           Esto permite definir los parámetros aceptados por el entorno
           entorno.  Esta información se emplea más adelante para revisar el
           número de argumentos de la orden «\begin», y permite especificar
           cual se debe traducir.  La sintaxis del argumento parmetros es la
           misma descrita para las órdenes.  El primer párametro de la orden
           «\begin» es el nombre del entorno.  No debe especificar este
           parámetro en la lista de parámetros. A continuación tiene unos
           ejemplos:
            % po4a: environment multicols {}
            % po4a: environment equation

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

       % po4a: separator entorno "expresin_regular"
           Indica que un entorno se debería dividir de acuerdo a la expresión
           regular dada.

           La expresión regular está delimitada por comillas. No debería crear
           ninguna referencia de apoyo. Debería usar (?:) si necesita un
           grupo. Puede precisar también algunos escapes.

           Por ejemplo, el módulo LaTeX usa la expresión regular "(?:&|\\\\)"
           para traducir cada célula de la tabla por separado (las líneas
           separan con '\\' y las células con '&').

           La noción 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 órdenes
           se ignorarán en este entorno.

           Si este entorno no se registró ya, po4a considerará que este
           entorno no acepta ningún argumento.

ESCRIBIR MÓDULOS DERIVADOS

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

           Los comentarios de un párrafo se insertan como comentarios del PO
           en la primera cadena traducida del párrafo.

       get_leading_command($buffer)
           Esta función devuelve:

           El nombre de la orden
               Si no se encuentra ninguna orden al principio del búfer dado,
               esta cadena estará vacía. Sólo se consideran las órdenes que se
               pueden separar. La serie asociativa (hash)
               «$separated_commands» contiene la lista separada por espacios
               de estas órdenes.

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

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

           El resto del búfer
               El resto del búfer después de la eliminación de la orden
               inicial y sus parámetros. Si no se encuentra ninguna orden, se
               devuelve a este campo el búfer original intacto.

       get_trailing_command($buffer)
           Lo mismo que get_leading_command, pero para las órdenes 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 función se define en «%translate_buffer_env» para el entorno
           actual, esta función se usará para traducir el búfer en lugar de
           «translate_buffer()».

       read
           Sobrecarga la lectura («read») de Transtractor

       read_file
           Lee un fichero recursivamente, añadiendo los ficheros incluidos que
           no están listados en la lista «@exclude_include». Los ficheros
           incluidos se buscan con la orden kpsewhich de la biblioteca
           Kpathsea.

           Exceptuando la parte de inclusión de ficheros, es una copia del
           «read» de Transtractor.

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

       parse_definition_line
           Analiza una linea de definición con la forma «% po4a: ».

           Consulte la sección PERSONALIZACIÓN DE OBJETOS EN LÍNEA para más
           detalles.

       is_closed
       docheader

FUNCIONES INTERNAS utilizadas para escribir analizadores derivados

       Las funciones de orden y entorno toman los siguientes argumentos
       (además del objeto «$self»):

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

       Los primeros 3 parámetros se extraen con «get_leading_command» o
       «get_trailing_command».

       Las funciones de orden y de entorno devuelven la traducción 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 módulo TeX sólo propone una orden de función y una orden de entorno:
       «generic_command» y «generic_environment».

       «generic_command» usa la información especificada por
       «register_generic_command», o añadiendo una definición para el fichero
       TeX:
        % po4a: command orden1 parmetros «generic_environment» usa la
       información especificada por «register_generic_environment» o añadiendo
       una definición al fichero de TeX:
        % po4a: environment entorno parmetros

       Ambas funciones sólo traducen los parámetros especificados como
       traducibles (con una '_'). «generic_environment» afijará el nombre del
       entorno a la pila del entorno, y «generic_command» afijará el nombre de
       la orden seguida por un identificador del parámetro (como {#7} o [#2]).

ESTADO DE ESTE MODULO

       Este módulo necesita más pruebas.

       Se ha probado con un libro y con la documentación de Python.

LISTA DE TAREAS PENDIENTES

       Detección automática de órdenes nuevas
           El módulo TeX podría analizar los argumentos de la orden nueva e
           intentar determinar el número de argumentos, su tipo y si se
           deberían traducir.

       Traducción del separador de entorno
           Cuando usa «\item» como un separador de entorno, el elemento
           argumento se añade a la siguiente cadena.

       Algunas órdenes se deberían añadir a la pila («stack») del entorno
           Estas órdenes se deberían especificar por parejas. Esto permitiría
           especificar órdenes que inician o finalizan un entorno literal.

       Otros
           Hay varios puntos etiquetados con TODO en el código.

FALLOS CONOCIDOS

       Hay varios puntos etiquetados con FIXME en el código.

VÉASE TAMBIÉN

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

AUTORES

        Nicolas François <nicolas.francois@centraliens.net>

DERECHO DE COPIA Y LICENCIA

       Copyright 2004, 2005 por Nicolas FRANÇOIS
       <nicolas.francois@centraliens.net>.

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