Provided by: po4a_0.41-1ubuntu1_all bug

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 da un aviso cuando falla. Puede
           tomar los siguientes valores: failed (predefinido), untranslated,
           noarg, translate_joined y translate_each.

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

       po4a(7), Locale::Po4a::TransTractor(3pm), Locale::Po4a::Pod(3pm).

AUTORES

        Denis Barbier <barbier@linuxfr.org>
        Nicolas François <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).