Perl - documentação incorporada

Você pode incorporar a documentação do Pod (texto antigo simples) em seus módulos e scripts Perl. A seguir está a regra para usar a documentação incorporada em seu código Perl -

Comece sua documentação com uma linha vazia, a =head1 comando no início e terminar com um =cut

O Perl irá ignorar o texto do Pod que você inseriu no código. A seguir está um exemplo simples de uso de documentação incorporada dentro de seu 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";

Quando o código acima é executado, ele produz o seguinte resultado -

Hello, World
Hello, Universe

Se você for colocar seu pod no final do arquivo e estiver usando uma marca de corte __END__ ou __DATA__, certifique-se de colocar uma linha vazia antes do primeiro comando do pod como segue, caso contrário, sem uma linha vazia antes o =head1, muitos tradutores não teriam reconhecido o =head1 como iniciar um bloco 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";

Quando o código acima é executado, ele produz o seguinte resultado -

Hello, World

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

Vamos dar mais um exemplo para o mesmo código sem ler a 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";

Quando o código acima é executado, ele produz o seguinte resultado -

Hello, World

O que é POD?

Pod é uma linguagem de marcação simples de usar para escrever documentação para Perl, programas Perl e módulos Perl. Existem vários tradutores disponíveis para converter o Pod em vários formatos, como texto simples, HTML, páginas de manual e muito mais. A marcação de pod consiste em três tipos básicos de parágrafos -

• Ordinary Paragraph - Você pode usar códigos de formatação em parágrafos comuns, para negrito, itálico, estilo de código, hiperlinks e muito mais.

• Verbatim Paragraph - Parágrafos literais são geralmente usados ​​para apresentar um bloco de código ou outro texto que não requer nenhuma análise ou formatação especial e que não deve ser quebrado.

• Command Paragraph- Um parágrafo de comando é usado para tratamento especial de pedaços inteiros de texto, geralmente como títulos ou partes de listas. Todos os parágrafos de comando começam com =, seguido por um identificador, seguido por um texto arbitrário que o comando pode usar como quiser. Os comandos atualmente reconhecidos são -

=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

Exemplos POD

Considere o seguinte POD -

=head1 SYNOPSIS
Copyright 2005 [TUTORIALSOPOINT].
=cut

Você pode usar pod2html utilitário disponível no Linux para converter POD acima em HTML, portanto, produzirá o seguinte resultado -

Em seguida, considere o seguinte exemplo -

=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

Quando você converte o POD acima em HTML usando pod2html, ele produzirá o seguinte 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.