LOCALE::PO4A::MAN.3PM(1) User Contributed Perl Documentation NOMBRE Locale::Po4a::Man - Convierte paginas de manual desde/a ficheros PO DESCRIPCION El objetivo del proyecto po4a (<>, PO para todo) es facilitar la traduccion (y mas interesante, el mantenimiento de las traducciones) usando las herramientas de gettext en ambitos donde no previstos, 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. Justificacion 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. Especificacion 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 en cursiva equivale a \fItexto\fP o ".I text" B -- texto en negrita equivale a \fBtexto\fP o ".B texto" R -- texto estandar equivale a \fRtext\fP CW -- 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. Transliteracion automatica 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 (<>) 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 <>> y <>> 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 controla 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. Esta opcion es obligatoria para usar po4a en paginas de manual generadas. Tenga en cuenta que traducir las paginas generadas en lugar de las fuentes suele ser mas fragil y, por tanto, una mala idea. 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 <>. Las paginas mdoc cuya seccion <> esta traducida no generaran cabecera ni pie de pagina alguna. De acuerdo a la pagina groff_mdoc, las secciones <>, <> y <> son obligatorias. No hay problemas conocidos con las secciones <> y <> cuando estan traducidas, pero tambien puede especificar estas secciones asi: -o mdoc=NAME,SYNOPSIS,DESCRIPTION Este problema de mdoc se puede resolver tambien con un apendice(<>) asi: PO4A-HEADER:mode=before;position=^.Dd .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name" Las siguientes opciones especifican el comportamiento de una macro definida por el usuario (con una peticion .de), o de una macro clasica que no es 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 ninguna prueba para verificar que una orden end coincida con su orden begin; cualquier orden de finalizacion finaliza el modo <>. Si tiene una macro begin (o end) que no tiene end (o begin), puede especificar un end ya existente (como <>) o begin (como <>) 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 muestra un aviso cuando falla. Puede tomar los siguientes valores: failed (el valor predefinido), untranslated, noarg, translate_joined y translate_each (vease en el punto anterior para una descripcion de estos valores). ESCRIBIR PAGINAS 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'ocultar' .B otro (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. Conclusion 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 (<> ;) 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). VEASE TAMBIEN Locale::Po4a::Pod(3pm), Locale::Po4a::TransTractor(3pm), po4a(7) AUTORES Denis Barbier Nicolas Francois Martin Quinson (mquinson#debian.org) TRADUCCION Jordi Vilalta Omar Campagne DERECHO DE COPIA Y LICENCIA Copyright (C) 2002-2008 SPI, Inc. Este programa es software libre; puede redistribuirlo y/o modificarlo bajo los terminos de la GPL v2.0 o posterior (consulte el archivo COPYING). perl v5.38.2 2024-06-26 LOCALE::PO4A::MAN.3PM(1)