Perl: documentación incorporada

Puede incrustar documentación de Pod (texto antiguo sin formato) en sus módulos y scripts de Perl. A continuación se muestra la regla para usar documentación incrustada en su código Perl:

Comience su documentación con una línea vacía, a =head1 comando al principio y finalizarlo con a =cut

Perl ignorará el texto del Pod que ingresó en el código. A continuación, se muestra un ejemplo simple de cómo usar documentación incrustada dentro de su código Perl:

#!/usr/bin/perl

print "Hello, World\n";

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
=cut

print "Hello, Universe\n";

Cuando se ejecuta el código anterior, produce el siguiente resultado:

Hello, World
Hello, Universe

Si va a colocar su Pod al final del archivo y está usando una marca de corte __END__ o __DATA__, asegúrese de poner una línea vacía allí antes del primer comando de Pod de la siguiente manera, de lo contrario, sin una línea vacía antes el =head1, muchos traductores no habrían reconocido el =head1 como iniciar un bloque de Pod.

#!/usr/bin/perl

print "Hello, World\n";

while(<DATA>) {
  print $_;
}

__END__

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";

Cuando se ejecuta el código anterior, produce el siguiente resultado:

Hello, World

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";

Tomemos un ejemplo más para el mismo código sin leer la parte DATA:

#!/usr/bin/perl

print "Hello, World\n";

__END__

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";

Cuando se ejecuta el código anterior, produce el siguiente resultado:

Hello, World

¿Qué es POD?

Pod es un lenguaje de marcado fácil de usar que se utiliza para escribir documentación para Perl, programas Perl y módulos Perl. Hay varios traductores disponibles para convertir Pod a varios formatos como texto sin formato, HTML, páginas de manual y más. El marcado de pod consta de tres tipos básicos de párrafos:

• Ordinary Paragraph - Puede utilizar códigos de formato en párrafos normales, en negrita, cursiva, estilo de código, hipervínculos y más.

• Verbatim Paragraph - Los párrafos textuales se utilizan generalmente para presentar un bloque de código u otro texto que no requiere ningún análisis o formato especial y que no debe ajustarse.

• Command Paragraph- Un párrafo de comando se usa para un tratamiento especial de fragmentos completos de texto, generalmente como encabezados o partes de listas. Todos los párrafos de comando comienzan con =, seguido de un identificador, seguido de texto arbitrario que el comando puede usar como le plazca. Los comandos actualmente reconocidos son:

=pod
=head1 Heading Text
=head2 Heading Text
=head3 Heading Text
=head4 Heading Text
=over indentlevel
=item stuff
=back
=begin format
=end format
=for format text...
=encoding type
=cut

Ejemplos de POD

Considere el siguiente POD:

=head1 SYNOPSIS
Copyright 2005 [TUTORIALSOPOINT].
=cut

Puedes usar pod2html utilidad disponible en Linux para convertir el POD anterior en HTML, por lo que producirá el siguiente resultado:

A continuación, considere el siguiente ejemplo:

=head2 An Example List

=over 4
=item * This is a bulleted list.
=item * Here's another item.
=back
=begin html
<p>
Here's some embedded HTML.  In this block I can
include images, apply <span style="color: green">
styles</span>, or do anything else I can do with
HTML.  pod parsers that aren't outputting HTML will
completely ignore it.
</p>

=end html

Cuando convierta el POD anterior en HTML usando pod2html, producirá el siguiente resultado:

An Example List
   This is a bulleted list.
   Here's another item.
Here's some embedded HTML. In this block I can include images, apply 
styles, or do anything else I can do with HTML. pod parsers that aren't 
outputting HTML will completely ignore it.