Perl/POD

POD es el acrónimo de Plain Old Documentation y consiste en un lenguaje de marcas para construir documentación técnica, generalmente dentro de los propios fuentes del lenguaje Perl.

Enlaces y referencias

• Enlaces externos:
  • Ref: perldoc.perl.org tiene una referencia muy actualizada del documento oficial de POD
  • Ref: Wikipedia - Plain Old Documentationen la versión inglesa posee una página muy completa.
• Enlaces internos:
  • Pod::Usage

Conceptos

Párrafos normales

Grupos de líneas (párrafos para entendernos) con una línea en blanco antes y otra después. Se pueden utilizar códigos de formato dentro de ellos.

Párrafos literales

Utilizados para incluir código fuente, ú otros textos que no requieren formato alguno, y que deben presentarse como están.

Se indican comenzando la primera línea con un sangrado de un espacio (mínimo) ó un tabulado. Comúnmente el resto de las líneas también se sangran.

Párrafos especiales

Aquellos que determinan un tratamiento especial para trozos de texto, normalmente encabezados ó listas de elementos.

Generalmente consisten en una única línea de texto cuyo primer caŕacter es un signo igual (=), le sigue un identificador de órden y, opcionalmente, un texto de tamaño y formato arbitrario que se usará como parámetro de la órden.

Atención: conviene recordar que estas órdenes no terminan en la misma línea, sino cuando acaba su párrafo, que como hemos visto se delimita con una línea en blanco. Por eso, y aunque algunos analizadores de código POD lo admitan es recomendable separar cada órden con una línea vacía.

Inicio y fin de documentación

=cut 

=pod

Estas dos órdenes marcan el comienzo y fin de una zona de documentación. Útil sobre todo para los analizadores POD y, cómo no, para el intérprete Perl.

Encabezados

=head1 Encabezado de primer nivel

=head2 Un elemento I<subversivo>

Están reconocidos los niveles uno al cuatro y el texto puede contener elementos de formato.

Listas

=over 4

=item * Un elefante

=item * Dos elefantes

=back

Para crear listas (ó indentar párrafos) se deben utilizar los tres elementos anteriores en el orden mostrado.

• Toda lista comienza con una órden =over y una indentación opcional.
• Los elementos van a continuación y consisten en:
  • La orden =item
  • Un asterisco para una la lista con viñetas ó un número para una lista enumerada.
  • Texto que puede contener elementos de formato.

• Una órden de cierre de lista =back con su correspondiente párrafo.

Asimismo conviene recordar que:

• Las listas pueden anidarse
• Las órdenes item no pueden situarse fuera de una lista.
• No pueden ir encabezados de ningún nivel dentro de una lista.

Zonas especiales

=begin nombre_formato

texto 

=end nombre_formato

=for nombre_formato texto

Estas órdenes permiten definir zonas especiales que no son interpretadas, generalmente, como código POD. En su lugar son pasadas directamente a programas de formato especial según el nombre (nombre_formato) indicado en la órden.

Mientras que las órdenes =begin y =end determinan una zona amplía, para situaciones en las que sólo queramos pasar un párrafo podemos usar =for.

La regla principal es que si el analizador/convertidor no reconoce la zona, debe ignorarla totalmente, por lo que se crean lo que podíamos llamar zonas invisibles y que pueden utilizarse para perl/pbp/documentacion.

Para algunos formatos será necesario prefijar el nombre con dos puntos (:) para señalar que el texto de la zona está en formato POD y que debe interpretarse como tal.

Códigos de formato

Tipografías

• I<text>: texto en itálica
• B<text>: texto en negrita
• C<text>: texto monoespaciado
• E<character>: carácter literal
  • E<lt>: carácter menor qué <
  • E<gt>: caŕacter mayor qué >
  • E<verbar>: barra vertical |
  • E<sol>: barra inclinada /
  • E<htmlname>: nombre de una entidad HTML.
  • E<number>: número de carácter dentro del juego de caracteres (ASCII/Latin1/Unicode).

• F<filename>: nombre y/ó ruta de archivo
• S<text>: texto no divisible en líneas.
• X<topic>: define topic como entrada en el índice.

Hiperenlaces

Dentro de los términos text, name y section, empleados más abajo, no pueden estar los caracteres / ni |, y cualquier carácter < y/ó > debe tener su pareja complementaria.

También recordar que una sección se indica mediante un encabezado (=head) ó un elemento de una lista (=item).

En los tres siguientes modos es posible definir un texto visible anteponiendo un campo text y separándolo con un carácter barra (|) como en:

L<the class methods|myclass/methods>

A página de manual: L<name>

Enlace a una página de manual Perl ó del sistema (man en UNIX); en éste último caso se puede incluir la sección entre paréntesis.

L<Net::Ping>
L<crontab(5)>

A una sección dentro de una página de manual: L<name/section>

Igual que el anterior, pero añadiendo una sección concreta separada por un carácter barra (/). La sección puede estar entrecomillada o no.

L<perl/"For Loops">
L<perlvar/$.>

A una sección en la misma página: L</section>

En donde sólo se añade la sección y se asume que la página es la misma en la que aparece el enlace.

L</"For Loops">
L</methods>

Enlace a un URL

Puede especificarse un URL completo anteponiendo el protocolo a la dirección, como en:

L<http://taquiones.net>

No es posible añadir un texto visible.

Recetario

Caracteres internacionales

Si la documentación está escrita en otro juego de caracteres distinto a Latin-1 o US-ASCII se debe indicar con una directiva especial:

=pod 

=encoding utf8

=head1 España

=cut

En caso de duda hay que consultar la lista de codificaciones soportadas.

Convertir a Postscript

Esta receta está tomada de la documentación de pod2man y muestra cómo se puede obtener un libro en PostScript de un conjunto de archivos POD conservando la numeración:

$ for m in $(find . -name "*.pod")
do
pod2man $m > $m.man
done
$ groff -man -rC1 -rD1 $(find . -name "*.man") > doc.ps