Perl POD Documentation
In Perl, you can embed POD (Plain Old Documentation) documents within modules or scripts.
POD is a simple and easy-to-use markup language.
POD document usage rules:
>
POD documents start with =head1 and end with =cut, with a blank line before =head1 and after =cut.
Perl ignores the documentation in POD. Here is an example:
Example
#!/usr/bin/perl
print "Hello, World\n";
=head1 Hello, World Example
This is a simple example of Perl.
=cut
print "Hello, tutorialpro\n";
Executing the above program, the output is:
Hello, World
Hello, tutorialpro
We can also use "__END__" or "__DATA__" to "comment out" all content after the line:
Example
#!/usr/bin/perl
print "Hello, World\n";
while(<DATA>){
print $_;
}
__END__
=head1 Hello, World Example
This is a simple example of Perl.
print "Hello, tutorialpro\n";
Executing the above program, the output is:
Hello, World
=head1 Hello, World Example
This is a simple example of Perl.
print "Hello, tutorialpro\n";
The following example does not read the POD document:
Example
#!/usr/bin/perl
print "Hello, World\n";
__END__
=head1 Hello, World Example
This is a simple example of Perl.
print "Hello, tutorialpro\n";
Executing the above program, the output is:
Hello, World
What is POD?
POD (Plain Old Documentation) is a simple and easy-to-use markup language, often used for writing documentation in Perl programs and modules.
POD converters can transform POD into many formats such as text, HTML, man, and more.
The POD markup language includes three basic types: ordinary, verbatim, and command.
-
Ordinary Paragraph: You can use formatting codes such as bold, italic, code style, underline, etc., in ordinary paragraphs.
-
Verbatim Paragraph: Verbatim paragraphs are used for code blocks or other parts that do not need the converter to process and do not require paragraph rearrangement.
-
Command Paragraph: Command paragraphs affect the entire document, typically used for setting headers or marking lists.
All command paragraphs (which are only one line long) start with "=" followed by an identifier. The subsequent text will be affected by this command. Commonly used commands include:
=pod (start document)
=head1 Header Text
=head2 Header Text
=head3 Header Text
=head4 Header Text
=over Indentation Spaces
=item Prefix
=back (end list)
=begin Document Format
=end End Document Format
=for Format Text
=encoding Encoding Type
=cut (end document)
In Perl, you can use pod2html to generate HTML format POD documents.
Consider the following POD example:
Example
=begin html
=encoding utf-8
=head1 tutorialpro.org
=cut
When using pod2html, this code will be copied as is.
Execute the pod2html command to convert it to HTML code:
$ pod2html test.pod > test.html
Open test.html in a browser, the link part is an index, displayed as follows:
The following example directly writes HTML in the POD document:
=begin html
=encoding utf-8
<h1>tutorialpro.org</h1>
<p> www.tutorialpro.org </p>
=end html
When using pod2html, this code will be copied as is.
Execute the pod2html command to convert it to HTML code:
$ pod2html test.pod > test.html
Open test.html in a browser, the link part is an index, displayed as follows: