Documentación POD de Perl

En Perl, se puede incrustar documentación POD (Plain Old Documentation) en módulos o scripts.

POD es un lenguaje de marcado simple y fácil de usar.

Reglas de uso de la documentación POD:

La documentación POD comienza con=head1comienza,=cuttermina,=head1antes y=cutdespués agregue una línea en blanco.

Perl ignora la documentación en POD. Ejemplo:

Ejemplo

#!/usr/bin/perl print "Hello, World\n"; =head1Ejemplo Hello, World Este es un ejemplo simple de Perl.=cut print "Hello, Ejemplo\n";

Ejecute el programa anterior, el resultado es:

Hello, World
Hello, Ejemplo

También podemos usar "__END__" o "__DATA__" para "comentar" todo el contenido después de la línea en la que aparecen:

Ejemplo

#!/usr/bin/perl print "Hello, World\n"; while(<DATA>){ print $_; } __END__ =head1Ejemplo Hello, World Este es un ejemplo simple de Perl. print "Hello, Ejemplo\n";

Ejecute el programa anterior, el resultado es:

Hello, World

=head1 Hello, World 实例
这是一个 Perl 的简单实例。
print "Hello, Ejemplo\n";

El siguiente ejemplo no lee la documentación POD:

Ejemplo

#!/usr/bin/perl print "Hello, World\n"; __END__ =head1Ejemplo Hello, World Este es un ejemplo simple de Perl. print "Hello, Ejemplo\n";

Ejecute el programa anterior, el resultado es:

Hello, World

¿Qué es POD?

Pod (Plain Old Documentation) es un lenguaje de marcado simple y fácil de usar, que se utiliza con frecuencia para escribir documentación en programas y módulos de Perl.

Los convertidores de Pod pueden convertir Pod a muchos formatos, como text, html, man, entre otros.

El lenguaje de marcado Pod incluye tres tipos básicos: normal, literal y de comando.

  • Párrafo normal: Puede usar códigos de formato en párrafos normales, como negrita, cursiva, estilo de código, subrayado, etc.

  • Párrafo literal: El párrafo literal se usa para bloques de código u otras partes que no requieren procesamiento por el convertidor, y no necesita reordenamiento de párrafos.

  • Párrafo de comando: El párrafo de comando actúa sobre todo el documento, generalmente se usa para configurar títulos o marcar listas.

    Todos los párrafos de comando (que solo tienen una línea de longitud) comienzan con "=", seguido de un identificador. El texto posterior será afectado por este comando. Los comandos ampliamente utilizados incluyen:

    =pod (开始文档)
=head1 标题文本
=head2 标题文本
=head3 标题文本
=head4 标题文本
=over 缩进空格数量
=item 前缀
=back (结束列表)
=begin 文档格式
=end 结束文档格式
=for 格式文本
=encoding 编码类型
=cut (文档结束)

En Perl, se puede usar pod2html **.pod >**.html para generar documentación POD en formato html.

Considere el siguiente ejemplo de POD:

Ejemplo

=beginhtml =encoding utf-8 =head1 Tutorial Ejemplo=cut

pod2html copiará este segmento de código tal cual.

Ejecute el comando pod2html para convertirlo a código HTML:

$ pod2html test.pod > test.html

Abra test.html en el navegador; la parte de los enlaces es el índice, como se muestra a continuación:

El siguiente ejemplo escribe HTML directamente en la documentación POD:

=begin html
=encoding utf-8

<h1>Ejemplo</h1>
<p> www.example.com </p>

=end html

pod2html copiará este segmento de código tal cual.

Ejecute el comando pod2html para convertirlo a código HTML:

$ pod2html test.pod > test.html

Abra test.html en el navegador; la parte de los enlaces es el índice, como se muestra a continuación:

Otras extensiones