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 L^ATEX 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.pl^5.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.

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

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

Texto normal

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

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