NOMBRE¶
Locale::Po4a::Pod - Convierte datos POD desde/a ficheros PO
SINOPSIS¶
use Locale::Po4a::Pod;
my $parser = Locale::Po4a::Pod->new (sentence => 0, width => 78);
# Lee el POD por la entrada estándar y escribe por la salida estándar.
$parser->parse_from_filehandle;
# Lee POD desde «fichero.pod» y escribe en «fichero.txt».
$parser->parse_from_file ('fichero.pod', 'fichero.txt');
DESCRIPCIÓN¶
Locale::Po4a::Pod es un módulo que asiste en la traducción de
documentación en formato POD (el lenguaje preferido para documentar Perl)
a otros lenguajes (humanos).
ESTADO DE ESTE MODULO¶
Opino que este módulo es muy estable, y sólo hay un fallo conocido con
/usr/lib/perl5/Tk/MainWindow.pod (y algunas otras páginas,
consulte más abajo) que contiene:
C<" #n">
Mala suerte, en la versión de po4a esto se separó en el espacio debido
al justificado. Como resultado, en la versión original la página de
manual contiene
" #n"
y el mio contiene
"" #n""
lo cual es lógico ya que C<foobar> se reescribe como
"foobar".
La lista completa de las páginas que dan este problema en mi máquina
(de 564 páginas; observe que esto depende de la puntuación elegida
para el justificado): /usr/lib/perl5/Tk/MainWindow.pod
/usr/share/perl/5.8.0/overload.pod /usr/share/perl/5.8.0/pod/perlapi.pod
/usr/share/perl/5.8.0/pod/perldelta.pod /usr/share/perl/5.8.0/pod/perlfaq5.pod
/usr/share/perl/5.8.0/pod/perlpod.pod /usr/share/perl/5.8.0/pod/perlre.pod
/usr/share/perl/5.8.0/pod/perlretut.pod
FUNCIONAMIENTO INTERNO¶
Como clase derivada de Pod::Parser, Locale::Po4a::Pod es compatible con los
mismos métodos e interfaces. Consulte Pod::Parser para más detalles;
brevemente, uno crea un nuevo analizador con
"Locale::Po4a::Pod->new()" y luego invoca «
parse_from_filehandle()» o bien «
parse_from_file()».
new() puede tomar opciones, en forma de pares llave/valor, que controlan
el comportamiento del analizador. Las opciones comunes reconocidas por todos
los hijos de Pod::Parser son:
- alt
- Si tiene un valor verdadero («true»), selecciona
un formato alternativo de salida que, entre otras cosas, utiliza un estilo
de cabecera diferente y marca las entradas =item con dos puntos en
el margen izquierdo. Falso por omisión.
- code
- Si tiene un valor verdadero, las partes no POD del fichero
de entrada se incluirán en la salida. Esto es útil para
visualizar código documentado con bloques POD, con el POD tratado y
el código dejado intacto.
- indent
- El número de espacios con el que sangrar texto
regular, y el sangrado por omisión de los bloques =over. Por
omisión vale 4.
- loose
- Si toma valor verdadero, se imprime una línea en
blanco después de las cabeceras =head1. De ser falso
(predefinido), no se imprimen líneas en blanco después de
=head1, pero sí después de =head2. Este es el
comportamiento predefinido porque éste es el formato esperado para
las páginas de manual; si está formateando documentos de texto
arbitrario, introducir ésta opción puede resultar en una salida
más agradable.
- quotes
- Ajusta las marcas de cita C<> alrededor del texto. Si
el valor es un único carácter, se utilizará para las marcas
izquierda y derecha; si son dos caracteres, se utilizará el primero
para la marca izquierda, y el segundo para la derecha; y si son cuatro
caracteres, los dos primeros se utilizarán como marca izquierda, y
los dos últimos como marca derecha.
También se le puede dar el valor especial none, en cuyo caso no
se añadirán comillas alrededor del texto C<>.
- sentence
- Si se define como verdadero, Locale::Po4a::Pod asumirá
que cada frase termina con dos espacios e intentará preservar
éste espaciado. Si se define como falso, todos los espacios
consecutivos encontrados en un párrafo que no se deba mantener tal
cual se comprimirán a un único espacio. Por omisión tiene
valor verdadero.
- width
- La columna a la cual se justifica el texto en el lado
derecho. Por omisión tiene un valor de 76.
VÉASE TAMBIÉN¶
Pod::Parser,
Locale::Po4a::Man(3pm),
Locale::Po4a::TransTractor(3pm),
po4a(7)
AUTORES¶
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
DERECHO DE COPIA Y LICENCIA¶
Copyright 2002 por SPI, inc.
Esto es software libre; puede redistribuirlo y/o modificarlo bajo las
condiciones de la licencia GPL (consulte el fichero COPYING).