Perl - Documentation intégrée

Vous pouvez intégrer la documentation Pod (Plain Old Text) dans vos modules et scripts Perl. Voici la règle pour utiliser la documentation intégrée dans votre code Perl -

Commencez votre documentation avec une ligne vide, a =head1 commande au début et terminez-la par un =cut

Perl ignorera le texte du pod que vous avez entré dans le code. Voici un exemple simple d'utilisation de la documentation intégrée dans votre code 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";

Lorsque le code ci-dessus est exécuté, il produit le résultat suivant -

Hello, World
Hello, Universe

Si vous allez placer votre Pod à la fin du fichier et que vous utilisez une marque de coupe __END__ ou __DATA__, assurez-vous de mettre une ligne vide avant la première commande de Pod comme suit, sinon sans ligne vide avant le =head1, de nombreux traducteurs n'auraient pas reconnu le =head1 comme démarrage d'un bloc 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";

Lorsque le code ci-dessus est exécuté, il produit le résultat suivant -

Hello, World

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

Prenons un autre exemple pour le même code sans lire la partie 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";

Lorsque le code ci-dessus est exécuté, il produit le résultat suivant -

Hello, World

Qu'est-ce que le POD?

Pod est un langage de balisage simple à utiliser utilisé pour écrire de la documentation pour Perl, les programmes Perl et les modules Perl. Il existe différents traducteurs disponibles pour convertir Pod en différents formats tels que le texte brut, le HTML, les pages de manuel, etc. Le balisage de pod se compose de trois types de paragraphes de base -

Ordinary Paragraph - Vous pouvez utiliser des codes de mise en forme dans des paragraphes ordinaires, pour le gras, l'italique, le style de code, les hyperliens, etc.
Verbatim Paragraph - Les paragraphes verbatim sont généralement utilisés pour présenter un bloc de code ou un autre texte qui ne nécessite aucune analyse ou mise en forme particulière, et qui ne doit pas être enveloppé.
Command Paragraph- Un paragraphe de commande est utilisé pour le traitement spécial de morceaux entiers de texte, généralement en tant que titres ou parties de listes. Tous les paragraphes de commande commencent par =, suivi d'un identifiant, suivi d'un texte arbitraire que la commande peut utiliser comme bon lui semble. Les commandes actuellement reconnues sont -

=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

Exemples de POD

Considérez le POD suivant -

=head1 SYNOPSIS
Copyright 2005 [TUTORIALSOPOINT].
=cut

Vous pouvez utiliser pod2html utilitaire disponible sur Linux pour convertir ci-dessus POD en HTML, donc il produira le résultat suivant -

Ensuite, considérons l'exemple suivant -

=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

Lorsque vous convertissez le POD ci-dessus en HTML à l'aide de pod2html, il produira le résultat suivant -

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.