Provided by: po4a_0.41-1ubuntu1_all bug

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