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).

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…