.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::Man 3pm"
.TH Locale::Po4a::Man 3pm "2023-01-03" "Herramientas de po4a" "Herramientas de po4a"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NOMBRE"
.IX Header "NOMBRE"
Locale::Po4a::Man \- Convierte páginas de manual desde/a ficheros \s-1PO\s0
.SH "DESCRIPCIÓN"
.IX Header "DESCRIPCIÓN"
El objetivo del proyecto po4a («PO for anything», \s-1PO\s0 para todo) es facilitar la traducción (y más interesante, el mantenimiento de las traducciones) usando las herramientas de gettext en ámbitos dónde no previstos, como la documentación.
.PP
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).
.SH "TRADUCIR CON PO4A::MAN"
.IX Header "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.
.SS "Justificación de texto"
.IX Subsection "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.
.PP
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.
.SS "Especificación del tipo de letra"
.IX Subsection "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 \s-1POD\s0 (documentación en línea de Perl):
.IP "I<texto> \*(-- texto en cursiva" 4
.IX Item "I<texto> texto en cursiva"
equivale a \efItexto\efP o \*(L".I text\*(R"
.IP "B<texto> \*(-- texto en negrita" 4
.IX Item "B<texto> texto en negrita"
equivale a \efBtexto\efP o \*(L".B texto\*(R"
.IP "R<texto> \*(-- texto estándar" 4
.IX Item "R<texto> texto estándar"
equivale a \efRtext\efP
.IP "CW<texto> \*(-- texto con ancho constante" 4
.IX Item "CW<texto> texto con ancho constante"
equivale a \ef(CWtexto\efP o \*(L".CW texto\*(R"
.PP
Comentario: El tipo \s-1CW\s0 no está disponible en todos los dispositivos groff. Se recomienda no usarla, pero se proporciona para su comodidad.
.SS "Transliteración automática de caracteres"
.IX Subsection "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:
.IP "guiones" 4
.IX Item "guiones"
Los guiones (\-) y signos de resta (\e\-) en las páginas de manual pasan a ser rayas simples (\-) en el fichero \s-1PO.\s0 Entonces, todas las rayas sufren una transliteración, pasando a ser signos de resta (\e\-) cuando se inserta la traducción en el documento de salida.
.Sp
Los traductores pueden forzar el guión usando el glifo de roff '\e[hy]' en sus traducciones.
.IP "espacios duros («non\-breaking spaces»)" 4
.IX Item "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 ('\e ').
.IP "las comillas en la transliteración" 4
.IX Item "las comillas en la transliteración"
«``» y «''» pasan a ser «\e*(lq» y «\e*(rq», respectivamente, después de la transliteración.
.Sp
Para evitar estas transliteraciones, los traductores pueden insertar un carácter de ancho cero de roff (p. ej., usando «`\e&`» o «'\e&'» respectivamente.
.SS "Introducir «<» y «>» en las traducciones"
.IX Subsection "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 \s-1POD\s0).
.SH "OPCIONES ACEPTADAS POR ESTE MODULO"
.IX Header "OPCIONES ACEPTADAS POR ESTE MODULO"
Estas son las opciones particulares de este módulo:
.IP "\fBdebug\fR" 4
.IX Item "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.
.IP "\fBverbose\fR" 4
.IX Item "verbose"
Aumenta el nivel de verbosidad.
.IP "\fBgroff_code\fR" 4
.IX Item "groff_code"
This option controls the behavior of the module when it encounter a .de, .ie or .if section. It can take the following values:
.RS 4
.IP "\fIfail\fR" 4
.IX Item "fail"
Este es el valor predefinido. El módulo fallará cuando encuentre una sección .de, .ie o .if.
.IP "\fIverbatim\fR" 4
.IX Item "verbatim"
Indica que las secciones .de, .ie y .if se deben copiar tal cual desde el original al documento traducido.
.IP "\fItranslate\fR" 4
.IX Item "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 \fIverbatim\fR.
.RE
.RS 4
.RE
.IP "\fBgenerated\fR" 4
.IX Item "generated"
This option specifies that the file was generated, and that po4a should not try to detect if the man pages was generated from another format.  This option is mandatory to use po4a on generated man pages.  Note that translating generated pages instead of sources ones is often more fragile, and thus a bad idea.
.IP "\fBmdoc\fR" 4
.IX Item "mdoc"
Esta opción sólo es de utilidad con páginas mdoc.
.Sp
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.
.Sp
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 también puede especificar estas secciones así:
\&\-o mdoc=NAME,SYNOPSIS,DESCRIPTION
.Sp
Este problema de mdoc se puede resolver también con un apéndice(«addendum») así:
 PO4A\-HEADER:mode=before;position=^.Dd
 .TH \s-1DOCUMENT_TITLE 1\s0 \*(L"Month day, year\*(R" \s-1OS\s0 \*(L"Section Name\*(R"
.PP
The following options specify the behavior of a user-defined macro (with a .de request), or of a classical macro that is not supported by po4a.  They take as argument a comma-separated list of macros.  For example:
.PP
.Vb 1
\& \-o noarg=FO,OB,AR \-o translate_joined=BA,ZQ,UX
.Ve
.PP
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.
.IP "\fBuntranslated\fR" 4
.IX Item "untranslated"
\&\fBuntranslated\fR indica que esta macro (en cuanto a sus argumentos) no precisan traducción.
.IP "\fBnoarg\fR" 4
.IX Item "noarg"
\&\fBnoarg\fR es como \fBuntranslated\fR, a excepción de que po4a revisará que no se añada ningún argumento a esta macro.
.IP "\fBtranslate_joined\fR" 4
.IX Item "translate_joined"
\&\fBtranslate_joined\fR indica a po4a que proponga la traducción de los argumentos de la macro.
.IP "\fBtranslate_each\fR" 4
.IX Item "translate_each"
Con \fBtranslate_each\fR, los argumentos se propondrán también para su traducción, sólo que se traducirá cada uno separadamente.
.IP "\fBno_wrap\fR" 4
.IX Item "no_wrap"
Esta opción toma como argumento una lista de parejas separadas por comas \fIbegin\fR:\fIend\fR, donde \fIbegin\fR y \fIend\fR son órdenes que delimitan el principio y final de una sección que no se debería justificar.
.Sp
Note: no test is done to ensure that an \fIend\fR command matches its \fIbegin\fR command; any ending command stop the no_wrap mode.  If you have a \fIbegin\fR (respectively \fIend\fR) macro that has no \fIend\fR (respectively \fIbegin\fR), you can specify an existing \fIend\fR (like fi) or \fIbegin\fR (like nf) as a counterpart.  These macros (and their arguments) won't be translated.
.IP "\fBinline\fR" 4
.IX Item "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á \fIfoo <.bar baz qux> quux\fR, siendo \fIbar\fR la orden que debería ser un elemento en línea, y \fIbaz qux\fR sus argumentos.
.IP "\fBunknown_macros\fR" 4
.IX Item "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: \fBfailed\fR (el valor predefinido), \fBuntranslated\fR, \fBnoarg\fR, \fBtranslate_joined\fR y \fBtranslate_each\fR (véase en el punto anterior para una descripción de estos valores).
.SH "ESCRIBIR PÁGINAS DE MANUAL COMPATIBLES CON PO4A::MAN"
.IX Header "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.
.PP
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.
.SS "No programe en nroff"
.IX Subsection "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).
.SS "Utilice el juego de macros simples"
.IX Subsection "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.
.PP
.Vb 11
\& ..               ."              .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
.Ve
.SS "Ocultar texto a po4a"
.IX Subsection "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 \fIotro\fR argumento, y \fIotro\fR puede también aparecer como el último elemento de una lista. En el primer caso, no se debería traducir \fIotro\fR. Y en el segundo, \fIotro\fR debería traducirse.
.PP
En tal caso, el autor puede evitar que po4a extraiga algunas cadenas usando algunos constructos especiales de groff:
.PP
.Vb 1
\& .if !\*(Aqpo4a\*(Aqocultar\*(Aq .B otro
.Ve
.PP
(esto requiere la opción \fB\-o groff_code=verbatim\fR)
.PP
También puede definir una nueva macro para automatizar ésto:
 .de IR_untranslated
 .    \s-1IR\s0 \e\e$@
 ..
.PP
.Vb 1
\& .IR_untranslated \e\-q ", " \e\-\e\-quiet
.Ve
.PP
(esto requiere las opciones \fB\-o groff_code=verbatim\fR y \fB\-o untranslated=IR_untranslated\fR; con este constructo, el condicional \fB.if !'po4a'hide'\fR no es estrictamente necesario ya que po4a no analizará el interior de la definición de macro)
.PP
o usando un alias
 .als IR_untranslated \s-1IR\s0
.PP
.Vb 1
\& .IR_untranslated \e\-q ", " \e\-\e\-quiet
.Ve
.PP
Esto requiere la opción \fB\-o untranslated=als,IR_untranslated\fR.
.SS "Conclusión"
.IX Subsection "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 \ec 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.
.PP
Por supuesto, otra posibilidad es usar otro formato, más amigable a los traductores (como \s-1POD\s0 usando po4a::pod, o uno de la familia de XMl, como \s-1SGML\s0), pero gracias a po4a::man ya no los necesita. Una vez dicho esto, si el formato de origen de su documentación es \s-1POD\s0 o \s-1XML,\s0 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 \s-1POD,\s0 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 \s-1POD,\s0 y se ignoran por po4a::man.
.PP
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…
.SH "ESTADO DE ESTE MODULO"
.IX Header "ESTADO DE ESTE MODULO"
Este módulo se puede usar con la mayoría de páginas de manual existentes.
.PP
Algunas pruebas se realizan con regularidad en sistemas Linux:
.IP "\(bu" 4
Una tercera parte de las páginas se rechazan porque se generaron a partir de otro formato compatible con po4a (por ejemplo, \s-1POD\s0 o \s-1SGML\s0).
.IP "\(bu" 4
El 10% de las páginas restantes se rechazan con un error (por ejemplo, una macro de groff no es compatible).
.IP "\(bu" 4
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)
.IP "\(bu" 4
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).
.SH "VÉASE TAMBIÉN"
.IX Header "VÉASE TAMBIÉN"
\&\fBLocale::Po4a::Pod\fR\|(3pm), \fBLocale::Po4a::TransTractor\fR\|(3pm), \fBpo4a\fR\|(7)
.SH "AUTORES"
.IX Header "AUTORES"
.Vb 3
\& Denis Barbier <barbier@linuxfr.org>
\& Nicolas François <nicolas.francois@centraliens.net>
\& Martin Quinson (mquinson#debian.org)
.Ve
.SH "TRADUCCION"
.IX Header "TRADUCCION"
.Vb 2
\& Jordi Vilalta <jvprat@gmail.com>
\& Omar Campagne <ocampagne@gmail.com>
.Ve
.SH "DERECHO DE COPIA Y LICENCIA"
.IX Header "DERECHO DE COPIA Y LICENCIA"
Copyright © 2002\-2008 \s-1SPI,\s0 Inc.
.PP
Esto es software libre; puede redistribuirlo y/o modificarlo bajo las condiciones de la licencia \s-1GPL\s0 (consulte el fichero \s-1COPYING\s0).