Provided by:
po4a_0.41-1ubuntu1_all 
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).