Provided by:
po4a_0.41-1ubuntu1_all 
NOMBRE
Locale::Po4a::Man - Convierte paginas de manual 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::Man es un modulo que asiste en la traduccion de
documentacion en formato nroff (el lenguaje de las paginas de manual) a
otros lenguajes (humanos).
TRADUCIR CON PO4A::MAN
Este modulo intenta facilitar la vida a los traductores. Para ello, el
texto presentado a los traductores no es una copia exacta del texto
encontrado en la pagina de manual. De hecho, las partes mas crudas del
formato nroff se ocultan de forma que los traductores no se lien con
ellas.
Justificaci'on de texto
Los parrafos sin sangrado se justifican automaticamente para el
traductor. Esto puede llevar a pequenas diferencias en la salida
generada, ya que las reglas de justificacion usadas por groff no son
muy claras. Por ejemplo, dos espacios despues de un parentesis se
mantienen a veces.
De todas formas, la diferencia solo sera sobre la posicion de los
espacios adicionales en el parrafo justificado, y pienso que vale la
pena.
Especificaci'on del tipo de letra
El primer cambio es sobre los cambios de la especificacion del tipo de
letra. En nroff hay varias formas de especificar si una palabra dada se
debe escribir en pequeno, negrita o cursiva. En el texto a traducir hay
solo una forma, tomada del formato POD (documentacion en linea de
Perl):
I<texto> -- texto en cursiva
equivale a \fItexto\fP o ".I text"
B<texto> -- texto en negrita
equivale a \fBtexto\fP o ".B texto"
R<texto> -- texto estandar
equivale a \fRtext\fP
CW<texto> -- texto con ancho constante
equivale a \f(CWtexto\fP o ".CW texto"
Comentario: El tipo CW no esta disponible en todos los dispositivos
groff. Se recomienda no usarla, pero se proporciona para su comodidad.
Transliteraci'on autom'atica de caracteres
Po4a realiza una transliteracion automatica de algunos caracteres para
facilitar la traduccion o revision de una. Esta es una lista de los
caracteres afectados por el proceso:
guiones
Los guiones (-) y signos de resta (\-) en las paginas de manual
pasan a ser rayas simples (-) en el fichero PO. Entonces, todas las
rayas sufren una transliteracion, pasando a ser signos de resta
(\-) cuando se inserta la traduccion en el documento de salida.
Los traductores pueden forzar el guion usando el glifo de roff
'\[hy]' en sus traducciones.
espacios duros (<<non-breaking spaces>>)
Los traductores pueden usar espacios duros en sus traducciones.
Tras la transliteracion, estos espacios duros (0xA0 en latin1) se
convertiran en un espacio duro de roff ('\ ').
las comillas en la transliteracion
<<``>> y <<''>> pasan a ser <<\*(lq>> y <<\*(rq>>, respectivamente,
despues de la transliteracion.
Para evitar estas transliteraciones, los traductores pueden
insertar un caracter de ancho cero de roff (p. ej., usando <<`\&`>>
o <<'\&'>> respectivamente.
Introducir <<<>> y <<>>> en las traducciones
Ya que estos caracteres se usan para delimitar las partes bajo una
modificacion de tipo de letra, no puede usarlos literalmente. Use
<<E<lt>>> y <<E<gt>>> en su lugar (una vez mas, al igual que en POD).
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.
verbose
Aumenta el nivel de verbosidad.
groff_code
Esta opcion permite cambiar el comportamiento del modulo cuando
encuentra una seccion .de, .ie o .if. Puede tomar los siguientes
valores:
fail
Este es el valor predefinido. El modulo fallara cuando
encuentre una seccion .de, .ie o .if.
verbatim
Indica que las secciones .de, .ie y .if se deben copiar tal
cual desde el original al documento traducido.
translate
Indica que las secciones .de, .ie y .if se propondran para su
traduccion. Solo deberia usar esta opcion de existir una cadena
traducible dentro de una de estas secciones. De no ser asi, se
deberia usar verbatim.
generated
Esta opcion especifica que ya se genero el fichero, y que po4a no
deberia intentar detectar si las paginas de manual se generaron a
partir de otro formato. Esto permite usar po4a en paginas de manual
generadas. Esta opcion no toma ningun argumento.
mdoc
Esta opcion solo es de utilidad con paginas mdoc.
Selecciona una compatibilidad mas estricta del formato mdoc
diciendo a po4a que no traduzca la seccion <<NAME>>. Las paginas
mdoc cuya seccion <<NAME>> esta traducida no generaran cabecera ni
pie de pagina alguna.
De acuerdo a la pagina groff_mdoc, las secciones <<NAME>>,
<<SYNOPSIS>> y <<DESCRIPTION>> son obligatorias. No hay problemas
conocidos con las secciones <<SYNOPSIS>> y <<DESCRIPTION>> cuando
estan traducidas, pero puede especificar estas secciones de la
siguiente manera: -o mdoc=NAME,SYNOPSIS,DESCRIPTION
Este problema de mdoc se puede resolver tambien con un apendice
(<<addendum>>) como el que sigue:
PO4A-HEADER:mode=before;position=^.Dd
.TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"
Las siguientes opciones permiten especificar el comportamiento de una
nueva macro (definida con una peticion .de), o de una macro no
compatible con po4a. Toman una lista separada por comas de macros como
argumento. Por ejemplo:
-o noarg=FO,OB,AR -o translate_joined=BA,ZQ,UX
Nota: si una macro no es compatible con po4a, y considera que es una
macro de roff estandar, deberia enviarlo al equipo de desarrollo de
po4a.
untranslated
untranslated indica que esta macro (en cuanto a sus argumentos) no
precisan traduccion.
noarg
noarg es como untranslated, a excepcion de que po4a revisara que no
se anada ningun argumento a esta macro.
translate_joined
translate_joined indica a po4a que proponga la traduccion de los
argumentos de la macro.
translate_each
Con translate_each, los argumentos se propondran tambien para su
traduccion, solo que se traducira cada uno separadamente.
no_wrap
Esta opcion toma como argumento una lista de parejas separadas por
comas begin:end, donde begin y end son ordenes que delimitan el
principio y final de una seccion que no se deberia justificar.
Nota: no se realiza ningun examen para verificar que una orden end
coincida con su orden begin; cualquier orden de finalizacion
finaliza el modo <<no_wrap>>. Si tiene una macro begin (o end) que
no tiene end (o begin), puede especificar un end ya existente (como
<<fi>>) o begin (como <<nf>>) como contrapartida. Estas macros (y
sus argumentos) no se traduciran.
inline
Esta opcion especifica una lista separada por comas de macros que
no deben dividir el parrafo actual. La cadena a traducir contendra
foo <.bar baz qux> quux, siendo bar la orden que deberia ser un
elemento en linea, y baz qux sus argumentos.
unknown_macros
Esta opcion indica a po4a como actuar cuando encuentre una macro
desconocida. Por omision, po4a da un aviso cuando falla. Puede
tomar los siguientes valores: failed (predefinido), untranslated,
noarg, translate_joined y translate_each.
ESCRIBIR P'AGINAS DE MANUAL COMPATIBLES CON PO4A::MAN
Este modulo es muy limitado, y siempre lo sera, debido a que no es un
interprete real de nroff. Seria posible hacer un interprete real de
nroff para permitir a los autores usar las macros existentes, o incluso
definir macros nuevas en sus paginas, pero no quisimos. Seria demasiado
dificil y no pensamos que fuera necesario. Opinamos que si los autores
de las paginas de manual quieren ver su produccion traducida, deben
adaptarse para facilitar el trabajo de los traductores.
Por lo tanto, el analizador de man implementado en po4a tiene algunas
limitaciones conocidas que no tenemos en mente corregir, y que
representan unos puntos debiles que debera evitar si quiere que los
traductores se interesen por su documentacion.
No programe en nroff
nroff es un lenguaje de programacion completo, con definiciones de
macros, condicionales y todo eso. Como este analizador no es un
analizador de nroff completo, fallara en paginas que utilicen esas
partes (hay unas 200 paginas asi en mi sistema).
Utilice el juego de macros simples
Aun hay algunas macros no compatibles con po4a::man. Esto es porque no
he conseguido encontrar documentacion sobre ellas. Aqui hay una lista
de las macros no soportadas usadas en mi maquina. Tenga en cuenta que
la lista no es exhaustiva ya que el programa falla en la primera macro
no soportada que encuentra. Si tiene alguna informacion sobre alguna de
estas macros, intentare anadir la compatibilidad. Debido a estas
macros, hay unas 250 paginas en mi maquina no accesibles a po4a::man.
.. ." .AT .b .bank
.BE ..br .Bu .BUGS .BY
.ce .dbmmanage .do .En
.EP .EX .Fi .hw .i
.Id .l .LO .mf
.N .na .NF .nh .nl
.Nm .ns .NXR .OPTIONS .PB
.pp .PR .PRE .PU .REq
.RH .rn .S< .sh .SI
.splitfont .Sx .T .TF .The
.TT .UC .ul .Vb .zZ
Ocultar texto a po4a
A veces, el autor sabe que hay partes no traducibles, las cuales po4a
no deberia extraer. Por ejemplo, una opcion puede aceptar otro
argumento, y otro puede tambien aparecer como el ultimo elemento de una
lista. En el primer caso, no se deberia traducir otro. Y en el segundo,
otro deberia traducirse.
En tal caso, el autor puede evitar que po4a extraiga algunas cadenas
usando algunos constructos especiales de groff:
.if !'po4a'hide' .B other
(esto requiere la opcion -o groff_code=verbatim)
Tambien puede definir una nueva macro para automatizar esto:
.de IR_untranslated
. IR \\$@
..
.IR_untranslated \-q ", " \-\-quiet
(esto requiere las opciones -o groff_code=verbatim y -o
untranslated=IR_untranslated; con este constructo, el condicional .if
!'po4a'hide' no es estrictamente necesario ya que po4a no analizara el
interior de la definicion de macro)
o usando un alias
.als IR_untranslated IR
.IR_untranslated \-q ", " \-\-quiet
(esto requiere la opcion -o untranslated=als,IR_untranslated)
Conclusi'on
Para resumir esta seccion, mantengase en lo simple, e intente no ser
demasiado listo cuando escriba sus paginas de manual. nroff le permite
hacer un monton de cosas que no estan soportadas por este analizador.
Por ejemplo, intente no trabajar con \c para interrumpir el procesado
de texto (como hacen 40 paginas en mi maquina). O asegurese de poner
los parametros de las macros en la misma linea que la macro en si. Ya
se que nroff lo acepta, pero tratarlo anadiria complicaciones al
analizador.
Por supuesto, otra posibilidad es usar otro formato, mas amigable a los
traductores (como POD usando po4a::pod, o uno de la familia de XMl,
como SGML), pero gracias a po4a::man ya no los necesita. Una vez dicho
esto, si el formato de origen de su documentacion es POD o XML, deberia
interesarle mas traducir el formato de origen y no el generado. En
muchos casos, po4a::man detectara las paginas generadas y le informara.
Incluso rechazara procesar las paginas generadas desde POD, ya que esas
paginas se tratan a la perfeccion con po4a::pod, y porque la version
nroff define un monton de macros para las que no queria escribir la
compatibilidad. En mi sistema, 1432 de las 4323 paginas son generadas a
partir de POD, y se ignoran por po4a::man.
En la mayoria de casos, po4a::man detectara el problema y se negara a
procesar la pagina, mostrando un mensaje adaptado. En algunos casos
extranos, el programa terminara sin ningun aviso, pero la salida sera
mala. Estos casos se llaman fallos (<<bugs>> ;) Si se encuentra con
algun caso asi, asegurese de comunicarlo, ademas de enviar un arreglo
cuando sea posible...
ESTADO DE ESTE MODULO
Este modulo se puede usar con la mayoria de paginas de manual
existentes.
Algunas pruebas se realizan con regularidad en sistemas Linux:
o Una tercera parte de las paginas se rechazan porque se generaron a
partir de otro formato compatible con po4a (por ejemplo, POD o
SGML).
o El 10% de las paginas restantes se rechazan con un error (por
ejemplo, una macro de groff no es compatible)
o Por ultimo, po4a acepta sin problema aparentes menos del 1% de las
paginas, pero con algunos asuntos de gravedad (por ejemplo,
palabras omitidas, o insercion de nuevas palabras)
o Las otras paginas se tratan normalmente sin diferencias mas
importantes que la alteracion del espaciado o el retorno automatico
de linea (con problemas de tipo de letra en menos del 10% de las
paginas procesadas).
V'EASE TAMBI'EN
po4a(7), Locale::Po4a::TransTractor(3pm), Locale::Po4a::Pod(3pm).
AUTORES
Denis Barbier <barbier@linuxfr.org>
Nicolas Francois <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
DERECHO DE COPIA Y LICENCIA
Copyright 2002-2008 por SPI, inc.
Esto es software libre; puede redistribuirlo y/o modificarlo bajo las
condiciones de la licencia GPL (consulte el fichero COPYING).