La Documentación en Perl

La documentación en Perl se hace en formato pod (plain old documentation). Esta documentación se inserta en nuestro programa. Se trata de un lenguaje de marcas. Las líneas que siguen a __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.

Conversión de pod a Otros Formatos

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, tkpod5.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.

Texto verbatim

Cuando un párrafo esta sangrado (comienza con un espacio o tabulador) se reproduce exactamente como aparece.

Un comando de párrafo

=head1 cabecera 
=head2 cabecera 
=item texto
=over N
=back
=cut
=pod
=for X
=begin X
=end X

Texto normal

El texto será formateado y se pueden usar secuencias de formateado como



Subsecciones
Casiano Rodríguez León
2009-10-04