oracular (3) Locale::Po4a::TeX.3pm.gz
NOMBRE
Locale::Po4a::TeX - Convierte 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 ámbitos dónde no
previstos, 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
esto no se adecua al 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. Este proceso
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 reajustar.
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 se deben interpretar literalmente.
Si este entorno no se registró ya, po4a considerará que este entorno no acepta ningún argumento.
Utilice estas opciones para modificar el comportamiento predeterminado de las órdenes definidas.
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 parámetros
Esto describe 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 mantiene un contexto más completo, y es útil para aquellas órdenes con
palabras cortas en sus parámetros, 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 parámetros 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 parámetros
Esto define los parámetros aceptados por el entorno env y especifica los que se deben traducir. Esta
información se emplea más adelante para revisar el número de argumentos de la orden «\begin». La
sintaxis del argumento parámetros es la misma descrita para las otras ó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 "expresión_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
add_comment
Agrega una cadena como un comentario para ser agregado alrededor del siguiente elemento traducido.
Esto es mayormente para el módulo texinfo, como comentarios son manipulados automáticamente en TeX.
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 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
parse
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 parámetros «generic_environment» usa la información especificada por
«register_generic_environment» o añadiendo al archivo TeX:
% po4a: environment entorno parámetros
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 deben especificar por parejas. Esto se puede usar para 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
Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)
AUTORES
Nicolas François <nicolas.francois@centraliens.net>
TRADUCCION
Jordi Vilalta <jvprat@gmail.com> Omar Campagne <ocampagne@gmail.com>
DERECHO DE COPIA Y LICENCIA
Copyright © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>. Este programa es software libre; puede redistribuirlo y/o modificarlo bajo los términos de la GPL v2.0 o posterior (consulte el archivo COPYING).