
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOMBRE

Locale::Po4a::Man - Convierte páginas de manual desde/a ficheros PO

=head1 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 ámbitos dónde no previstos, 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).

=head1 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.

=head2 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.

=head2 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):

=over

=item IE<lt>textoE<gt> -- texto en cursiva

equivale a \fItexto\fP o ".I text"

=item BE<lt>textoE<gt> -- texto en negrita

equivale a \fBtexto\fP o ".B texto"

=item RE<lt>textoE<gt> -- texto estándar

equivale a \fRtext\fP

=item CWE<lt>textoE<gt> -- texto con ancho constante

equivale a \f(CWtexto\fP o ".CW texto"

=back

Comentario: El tipo CW no está disponible en todos los dispositivos
groff. Se recomienda no usarla, pero se proporciona para su comodidad.

=head2 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:

=over

=item 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.

=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 ('\ ').

=item 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.

=back

=head2 Introducir «E<lt>» y «E<gt>» 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
«EE<lt>ltE<gt>» y «EE<lt>gtE<gt>» en su lugar (una vez más, al igual que en
POD).

=head1 OPCIONES ACEPTADAS POR ESTE MODULO

Estas son las opciones particulares de este módulo:

=over

=item B<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.

=item B<verbose>

Aumenta el nivel de verbosidad.

=item B<groff_code>

Esta opción controla el comportamiento del módulo cuando encuentra una
sección .de, .ie o .if. Puede tomar los siguientes valores:

=over

=item I<fail>

Este es el valor predefinido. El módulo fallará cuando encuentre una sección
.de, .ie o .if.

=item I<verbatim>

Indica que las secciones .de, .ie y .if se deben copiar tal cual desde el
original al documento traducido.

=item I<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
I<verbatim>.

=back

=item B<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. Esta opción es obligatoria para usar po4a en páginas de manual
generadas. Tenga en cuenta que traducir las páginas generadas en lugar de
las fuentes suele ser más frágil y, por tanto, una mala idea.

=item B<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.

According to the groff_mdoc page, the NAME, SYNOPSIS and DESCRIPTION
sections are mandatory.
There are no known issues with translated SYNOPSIS or DESCRIPTION section,
but you can also specify these sections this way:
 -o mdoc=NAME,SYNOPSIS,DESCRIPTION

This mdoc issue can also be solved with an addendum like this one:
 PO4A-HEADER:mode=before;position=^.Dd
 .TH DOCUMENT_TITLE 1 "Month day, year" OS "Section Name"

=back

Las siguientes opciones especifican el comportamiento de una macro definida
por el usuario (con una petición .de), o de una macro clásica 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 estándar, debería enviarlo al equipo de desarrollo de po4a.

=over

=item B<untranslated>

B<untranslated> indica que esta macro (en cuanto a sus argumentos) no
precisan traducción.

=item B<noarg>

B<noarg> es como B<untranslated>, a excepción de que po4a revisará que no se
añada ningún argumento a esta macro.

=item B<translate_joined>

B<translate_joined> indica a po4a que proponga la traducción de los
argumentos de la macro.

=item B<translate_each>

Con B<translate_each>, los argumentos se propondrán también para su
traducción, sólo que se traducirá cada uno separadamente.

=item B<no_wrap>

Esta opción toma como argumento una lista de parejas separadas por comas
I<begin>:I<end>, donde I<begin> y I<end> son órdenes que delimitan el
principio y final de una sección que no se debería justificar.

Nota: no se realiza ninguna prueba para verificar que una orden I<end>
coincida con su orden I<begin>; cualquier orden de finalización finaliza el
modo «no_wrap». Si tiene una macro I<begin> (o I<end>) que no tiene I<end>
(o I<begin>), puede especificar un I<end> ya existente (como «fi») o
I<begin> (como «nf») como contrapartida. Estas macros (y sus argumentos) no
se traducirán.

=item B<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á I<foo E<lt>.bar
baz quxE<gt> quux>, siendo I<bar> la orden que debería ser un elemento en
línea, y I<baz qux> sus argumentos.

=item B<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: B<failed> (el valor predefinido), B<untranslated>,
B<noarg>, B<translate_joined> y B<translate_each> (véase en el punto
anterior para una descripción de estos valores).

=back

=head1 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.

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

=head2 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

=head2 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 I<otro> argumento, y
I<otro> puede también aparecer como el último elemento de una lista. En el
primer caso, no se debería traducir I<otro>. Y en el segundo, I<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 B<-o groff_code=verbatim>)

A new macro can also be defined to automate this:
 .de IR_untranslated
 .    IR \\$@
 ..

 .IR_untranslated \-q ", " \-\-quiet

(esto requiere las opciones B<-o groff_code=verbatim> y B<-o
untranslated=IR_untranslated>; con este constructo, el condicional B<.if
!'po4a'hide'> no es estrictamente necesario ya que po4a no analizará el
interior de la definición de macro)

or using an alias:
 .als IR_untranslated IR

 .IR_untranslated \-q ", " \-\-quiet

Esto requiere la opción B<-o untranslated=als,IR_untranslated>.

=head2 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…

=head1 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:

=over 4

=item *

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

=item *

El 10% de las páginas restantes se rechazan con un error (por ejemplo, una
macro de groff no es compatible).

=item *

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)

=item *

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

=back

=head1 VÉASE TAMBIÉN

L<Locale::Po4a::Pod(3pm)>, L<Locale::Po4a::TransTractor(3pm)>,
L<po4a(7)|po4a.7>

=head1 AUTORES

 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)


=head1 TRADUCCION

 Jordi Vilalta <jvprat@gmail.com>
 Omar Campagne <ocampagne@gmail.com>

=head1 DERECHO DE COPIA Y LICENCIA

Copyright © 2002-2008 SPI, Inc.

Este programa es software libre; puede redistribuirlo y/o modificarlo bajo
los términos de la GPL v2.0 o posterior (consulte el archivo COPYING).
