Perl - Eingebettete Dokumentation

Sie können die Pod-Dokumentation (Plain Old Text) in Ihre Perl-Module und -Skripte einbetten. Im Folgenden finden Sie die Regel für die Verwendung eingebetteter Dokumentation in Ihrem Perl-Code:

Beginnen Sie Ihre Dokumentation mit einer leeren Zeile, a =head1 Befehl am Anfang und beenden Sie es mit einem =cut

Perl ignoriert den Pod-Text, den Sie in den Code eingegeben haben. Im Folgenden finden Sie ein einfaches Beispiel für die Verwendung eingebetteter Dokumentation in Ihrem Perl-Code:

#!/usr/bin/perl

print "Hello, World\n";

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

print "Hello, Universe\n";

Wenn der obige Code ausgeführt wird, wird das folgende Ergebnis erzeugt:

Hello, World
Hello, Universe

Wenn Sie Ihren Pod am Ende der Datei platzieren und eine Schnittmarke __END__ oder __DATA__ verwenden, stellen Sie sicher, dass vor dem ersten Pod-Befehl wie folgt eine leere Zeile eingefügt wird, andernfalls ohne vorherige leere Zeile das =head1Viele Übersetzer hätten das = nicht erkannthead1 als Start eines Pod-Blocks.

#!/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";

Wenn der obige Code ausgeführt wird, wird das folgende Ergebnis erzeugt:

Hello, World

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

Nehmen wir noch ein Beispiel für denselben Code, ohne den DATA-Teil zu lesen -

#!/usr/bin/perl

print "Hello, World\n";

__END__

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

Wenn der obige Code ausgeführt wird, wird das folgende Ergebnis erzeugt:

Hello, World

Was ist POD?

Pod ist eine einfach zu verwendende Markup-Sprache, die zum Schreiben von Dokumentationen für Perl-, Perl-Programme und Perl-Module verwendet wird. Für die Konvertierung von Pod in verschiedene Formate wie Nur-Text, HTML, Manpages und mehr stehen verschiedene Übersetzer zur Verfügung. Das Pod-Markup besteht aus drei grundlegenden Arten von Absätzen:

Ordinary Paragraph - Sie können Formatierungscodes in normalen Absätzen für Fettdruck, Kursivschrift, Codestil, Hyperlinks und mehr verwenden.
Verbatim Paragraph - Wörtliche Absätze werden normalerweise zum Präsentieren eines Codeblocks oder eines anderen Textes verwendet, für den keine spezielle Analyse oder Formatierung erforderlich ist und der nicht umbrochen werden sollte.
Command Paragraph- Ein Befehlsabsatz wird zur speziellen Behandlung ganzer Textblöcke verwendet, normalerweise als Überschriften oder Teile von Listen. Alle Befehlsabsätze beginnen mit =, gefolgt von einem Bezeichner, gefolgt von einem beliebigen Text, den der Befehl nach Belieben verwenden kann. Derzeit erkannte Befehle sind -

=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

POD-Beispiele

Betrachten Sie den folgenden POD -

=head1 SYNOPSIS
Copyright 2005 [TUTORIALSOPOINT].
=cut

Sie können verwenden pod2html Unter Linux verfügbares Dienstprogramm zum Konvertieren des obigen POD in HTML, sodass das folgende Ergebnis erzielt wird:

Betrachten Sie als nächstes das folgende Beispiel:

=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

Wenn Sie den obigen POD mit pod2html in HTML konvertieren, wird das folgende Ergebnis angezeigt:

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.