Provided by: po4a_0.47-2_all 
NOMBRE
Locale::Po4a::Man - Convierte páginas de manual 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::Man es un módulo que asiste en la traducción de documentación en formato
nroff (el lenguaje de las páginas de manual) a otros lenguajes (humanos).
TRADUCIR CON PO4A::MAN
Este módulo 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 página de manual. De
hecho, las partes más crudas del formato nroff se ocultan de forma que los traductores no
se líen con ellas.
Justificación de texto
Los párrafos sin sangrado se justifican automáticamente para el traductor. Esto puede
llevar a pequeñas diferencias en la salida generada, ya que las reglas de justificación
usadas por groff no son muy claras. Por ejemplo, dos espacios después de un paréntesis se
mantienen a veces.
De todas formas, la diferencia sólo será sobre la posición de los espacios adicionales en
el párrafo justificado, y pienso que vale la pena.
Especificación del tipo de letra
El primer cambio es sobre los cambios de la especificación del tipo de letra. En nroff hay
varias formas de especificar si una palabra dada se debe escribir en pequeño, negrita o
cursiva. En el texto a traducir hay solo una forma, tomada del formato POD (documentación
en línea 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 estándar
equivale a \fRtext\fP
CW<texto> -- texto con ancho constante
equivale a \f(CWtexto\fP o ".CW texto"
Comentario: El tipo CW no está disponible en todos los dispositivos groff. Se recomienda
no usarla, pero se proporciona para su comodidad.
Transliteración automática de caracteres
Po4a realiza una transliteración automática de algunos caracteres para facilitar la
traducción o revisión de una. Esta es una lista de los caracteres afectados por el
proceso:
guiones
Los guiones (-) y signos de resta (\-) en las páginas de manual pasan a ser rayas
simples (-) en el fichero PO. Entonces, todas las rayas sufren una transliteración,
pasando a ser signos de resta (\-) cuando se inserta la traducción en el documento de
salida.
Los traductores pueden forzar el guión 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
transliteración, estos espacios duros (0xA0 en latin1) se convertirán en un espacio
duro de roff ('\ ').
las comillas en la transliteración
«``» y «''» pasan a ser «\*(lq» y «\*(rq», respectivamente, después de la
transliteración.
Para evitar estas transliteraciones, los traductores pueden insertar un carácter 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 modificación de tipo de
letra, no puede usarlos literalmente. Use «E<lt>» y «E<gt>» en su lugar (una vez más, al
igual que en POD).
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.
verbose
Aumenta el nivel de verbosidad.
groff_code
Esta opción permite cambiar el comportamiento del módulo cuando encuentra una sección
.de, .ie o .if. Puede tomar los siguientes valores:
fail
Este es el valor predefinido. El módulo fallará cuando encuentre una sección .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 propondrán para su traducción. Solo
debería usar esta opción de existir una cadena traducible dentro de una de estas
secciones. De no ser así, se debería usar verbatim.
generated
Esta opción especifica que ya se generó el fichero, y que po4a no debería intentar
detectar si las páginas de manual se generaron a partir de otro formato. Esto permite
usar po4a en páginas de manual generadas. Esta opción no toma ningún argumento.
mdoc
Esta opción sólo es de utilidad con páginas mdoc.
Selecciona una compatibilidad más estricta del formato mdoc diciendo a po4a que no
traduzca la sección «NAME». Las páginas mdoc cuya sección «NAME» está traducida no
generarán cabecera ni pié de página alguna.
De acuerdo a la página groff_mdoc, las secciones «NAME», «SYNOPSIS» y «DESCRIPTION»
son obligatorias. No hay problemas conocidos con las secciones «SYNOPSIS» y
«DESCRIPTION» cuando están traducidas, pero puede especificar estas secciones de la
siguiente manera: -o mdoc=NAME,SYNOPSIS,DESCRIPTION
Este problema de mdoc se puede resolver también con un apéndice («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 petición .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
estándar, debería enviarlo al equipo de desarrollo de po4a.
untranslated
untranslated indica que esta macro (en cuanto a sus argumentos) no precisan
traducción.
noarg
noarg es como untranslated, a excepción de que po4a revisará que no se añada ningún
argumento a esta macro.
translate_joined
translate_joined indica a po4a que proponga la traducción de los argumentos de la
macro.
translate_each
Con translate_each, los argumentos se propondrán también para su traducción, sólo que
se traducirá cada uno separadamente.
no_wrap
Esta opción toma como argumento una lista de parejas separadas por comas begin:end,
donde begin y end son órdenes que delimitan el principio y final de una sección que no
se debería justificar.
Nota: no se realiza ningún examen para verificar que una orden end coincida con su
orden begin; cualquier orden de finalización 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 traducirán.
inline
Esta opción especifica una lista separada por comas de macros que no deben dividir el
párrafo actual. La cadena a traducir contendrá foo <.bar baz qux> quux, siendo bar la
orden que debería ser un elemento en línea, y baz qux sus argumentos.
unknown_macros
Esta opción indica a po4a cómo actuar cuando encuentre una macro desconocida. Por
omisión, po4a muestra un aviso cuando falla. Puede tomar los siguientes valores:
failed (el valor predefinido), untranslated, noarg, translate_joined y translate_each
(véase en el punto anterior para una descripción de estos valores).
ESCRIBIR PÁGINAS DE MANUAL COMPATIBLES CON PO4A::MAN
Este módulo es muy limitado, y siempre lo será, debido a que no es un intérprete real de
nroff. Sería posible hacer un intérprete real de nroff para permitir a los autores usar
las macros existentes, o incluso definir macros nuevas en sus páginas, pero no quisimos.
Sería demasiado difícil y no pensamos que fuera necesario. Opinamos que si los autores de
las páginas de manual quieren ver su producción 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 débiles que
deberá evitar si quiere que los traductores se interesen por su documentación.
No programe en nroff
nroff es un lenguaje de programación completo, con definiciones de macros, condicionales y
todo eso. Como este analizador no es un analizador de nroff completo, fallará en páginas
que utilicen esas partes (hay unas 200 páginas así en mi sistema).
Utilice el juego de macros simples
Aún hay algunas macros no compatibles con po4a::man. Esto es porque no he conseguido
encontrar documentación sobre ellas. Aquí hay una lista de las macros no soportadas usadas
en mi máquina. 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 información sobre alguna de
estas macros, intentaré añadir la compatibilidad. Debido a estas macros, hay unas 250
páginas en mi máquina 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 debería extraer.
Por ejemplo, una opción puede aceptar otro argumento, y otro puede también aparecer como
el último elemento de una lista. En el primer caso, no se debería traducir otro. Y en el
segundo, otro debería 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 opción -o groff_code=verbatim)
También puede definir una nueva macro para automatizar ésto:
.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 analizará el interior de la definición de macro)
o usando un alias
.als IR_untranslated IR
.IR_untranslated \-q ", " \-\-quiet
(esto requiere la opción -o untranslated=als,IR_untranslated)
Conclusión
Para resumir esta sección, manténgase en lo simple, e intente no ser demasiado listo
cuando escriba sus páginas de manual. nroff le permite hacer un montón de cosas que no
están soportadas por este analizador. Por ejemplo, intente no trabajar con \c para
interrumpir el procesado de texto (como hacen 40 páginas en mi máquina). O asegúrese de
poner los parámetros de las macros en la misma línea que la macro en sí. Ya sé que nroff
lo acepta, pero tratarlo añadiría complicaciones al analizador.
Por supuesto, otra posibilidad es usar otro formato, más 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 documentación es POD o
XML, debería interesarle más traducir el formato de origen y no el generado. En muchos
casos, po4a::man detectará las páginas generadas y le informará. Incluso rechazará
procesar las páginas generadas desde POD, ya que esas páginas se tratan a la perfección
con po4a::pod, y porque la versión nroff define un montón de macros para las que no quería
escribir la compatibilidad. En mi sistema, 1432 de las 4323 páginas son generadas a partir
de POD, y se ignoran por po4a::man.
En la mayoría de casos, po4a::man detectará el problema y se negará a procesar la página,
mostrando un mensaje adaptado. En algunos casos extraños, el programa terminará sin ningún
aviso, pero la salida será mala. Estos casos se llaman fallos («bugs» ;) Si se encuentra
con algún caso así, asegúrese de comunicarlo, además de enviar un arreglo cuando sea
posible...
ESTADO DE ESTE MODULO
Este módulo se puede usar con la mayoría de páginas de manual existentes.
Algunas pruebas se realizan con regularidad en sistemas Linux:
• Una tercera parte de las páginas se rechazan porque se generaron a partir de otro
formato compatible con po4a (por ejemplo, POD o SGML).
• El 10% de las páginas restantes se rechazan con un error (por ejemplo, una macro de
groff no es compatible)
• Por último, po4a acepta sin problema aparentes menos del 1% de las páginas, pero con
algunos asuntos de gravedad (por ejemplo, palabras omitidas, o inserción de nuevas
palabras)
• Las otras páginas se tratan normalmente sin diferencias más importantes que la
alteración del espaciado o el retorno automático de línea (con problemas de tipo de
letra en menos del 10% de las páginas procesadas).
VÉASE TAMBIÉN
Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)
AUTORES
Denis Barbier <barbier@linuxfr.org>
Nicolas François <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
TRADUCCION
Jordi Vilalta <jvprat@gmail.com>
Omar Campagne <ocampagne@gmail.com>
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).