__END__
en el esqueleto generado por h2xs
(véase la sección 5.17)
muestran el
uso de pod
. Cuando Perl encuentra un comando pod
(todos los comandos comienzan por el signo igual) ignora las líneas a las que afecta.
Para indicar el final de una zona de documentación
se usa el comando =cut al comienzo de un nuevo párrafo.
Existe un buen número de utilidades que permiten pasar de formato
pod
a casi cualquier formato: pod2html
, pod2man
,
pod2latex, pod2ps
, pod2text
, pod2pdf.pl
, etc.
Un traductor pod-to-XXX
lee un fichero en formato
pod
párrafo por párrafo y lo traslada al formato XXX
.
Por ejemplo, para convertir a LATEX la documentación de perlpod
puedes escribir algo como:
pod2latex -full -prefile preamble.tex lib/Parse/Eyapp.pm
Para convertir a pdf
puedes usar
pod2pdf.pl5.3:
pod2pdf.pl [options] filename.pod >filename.pdf perldoc -u <Module::Name> | pod2pdf.pl [options] >filename.pdf
Una herramienta que permite el proceso inverso, esto es
pasar de formato man
a otros formatos es rman
5.4.
Si se ha instalado la documentación de Perl en tu sistema, puedes
acceder a ella utilizando info
, man
,
tkpod
5.5 o perldoc
.
La orden man perl
te mostrará las diferentes secciones existentes
y sobre que tratan. Asi man perlboot
te introducirá en la
programación orientada a objetos en Perl.
Para saber mas sobre el lenguaje de marcas pod
escribe
man perlpod
.
Un documento POD consiste de párrafos separados por líneas en blanco. Existen tres tipos de párrafos: verbatim, comandos y texto.
Cuando un párrafo esta sangrado (comienza con un espacio o tabulador) se reproduce exactamente como aparece.
=head1 cabecera =head2 cabecera =item texto =over N =back =cut =pod =for X =begin X =end X
=pod
, =cut
Es útil cuando mezclas código y documentación. Le indica a Perl
que lo que sigue es documentación hasta que se alcance el siguiente
=cut
.
=head1
, =head2
Primer y segundo nivel de encabezamiento.
El texto cabecera
debe estar en el mismo párrafo que la directiva.
=over
, =back
, =item
=over
comienza una lista, =back
la termina
y los elementos de la lista se especifican con =item
.
El número que se le pasa a =over
indica el sangrado de los
items.
Veamos un ejemplo:
=over 4 =item * Bla, bla, primer item =item * Mas bla, bla, segundo item =back
Mantenga la consitencia en la presentación: use =item *
para producir puntos o bien la forma =item 1.
, =item 2.
, etc.
=for
, =begin
, =end
Nos permiten incluir secciones que no contienen texto POD
sino que van dirigidas a formatos especiales.
La directiva =for
tiene como ámbito el siguiente párrafo:
=for html <br> <p> Esto sólo aparece en HTML</p>
Mientras que =begin
y =end
delimitan el texto en cuestión.
Ademas de html
, otros nombres que se aceptan son
roff
, man
, latex
, tex
y text
.
I<texto>
itálicas
B<texto>
negritas
C<texto>
código literal
S<texto>
texto que no se puede romper por los espacios.
F<fichero>
usado para nombres de fichero
L<texto>
un enlace a un nombre en el manual.
E<escape>
: E<lt> E<gt> E<n>
(n es un número)