Perl Embedded Documentation

Perl - Embedded Documentation (POD)

Perl allows you to embed documentation directly within your code using a simple markup language called POD (Plain Old Documentation). This is the standard way to document Perl modules and scripts.

Key rules for embedding POD in your Perl code:

• Start your documentation with a POD command like =head1 on a new line.
• End your documentation block with a =cut command on a new line.
• The Perl interpreter will ignore any text between these POD markers.

Here’s a simple example:

#!/usr/bin/perl
use strict;
use warnings;

print "Hello, World\n";

=head1 Hello, World Example

This example demonstrates very basic syntax of Perl and POD.

=cut

print "Hello, Universe\n";

When the above code is executed, it produces the following result (the POD content is ignored by the interpreter):

Hello, World
Hello, Universe

If you place POD at the end of your file, especially after an __END__ or __DATA__ marker, ensure there’s an empty line before the first POD command (e.g., =head1). This helps many POD translators correctly identify the start of a POD block.

Example with __DATA__:

#!/usr/bin/perl
use strict;
use warnings;

print "Hello, World from script\n";

while (my $line = <DATA>) {
    print "Data: $line";
}

__DATA__
This is some data.

=head1 POD at the End

This POD block is after __DATA__.
It will be read as data by the above loop if not for a =cut before it, or careful parsing.
Typically, POD after __DATA__ is for documentation purposes and not meant to be read by the script's data reading logic unless specifically intended.

=cut
This line is after =cut and __DATA__, so it's also data.

When the above code is executed, it produces (note how POD commands are treated as data here):

Hello, World from script
Data: This is some data.
Data:
Data: =head1 POD at the End
Data:
Data: This POD block is after __DATA__.
Data: It will be read as data by the above loop if not for a =cut before it, or careful parsing.
Data: Typically, POD after __DATA__ is for documentation purposes and not meant to be read by the script's data reading logic unless specifically intended.
Data:
Data: =cut
Data: This line is after =cut and __DATA__, so it's also data.

If the POD is meant purely for documentation and not to be mixed with data read from __DATA__, it’s common to place it before __DATA__ or ensure the data reading logic stops before the POD section if it’s intermingled.

What is POD?

POD is a lightweight markup language for documenting Perl code. It’s designed to be easy to read in its raw form and can be converted into various other formats like HTML, man pages, and plain text using tools like perldoc or modules from CPAN (e.g., Pod::Simple).

POD markup consists of three basic kinds of paragraphs:

• Ordinary Paragraph: Regular text. You can use formatting codes for bold (B<>), italic (I<>), code style (C<>), links (L<>), and more.
• Verbatim Paragraph: Preceded by at least one space or tab. Used for code blocks or text that shouldn’t be reformatted or wrapped. No formatting codes are interpreted within verbatim paragraphs.
• Command Paragraph: Starts with = followed by an identifier (e.g., =head1, =item). These commands structure the document, create headings, lists, etc.

Common POD Commands:

=pod
=head1 Major Heading Text
=head2 Secondary Heading Text
=head3 Tertiary Heading Text
=head4 Quaternary Heading Text
=over indentlevel (e.g., =over 4)
=item text or * for bullet
=back
=begin format_name (e.g., =begin html)
=end format_name
=for format_name text...
=encoding encoding_name (e.g., =encoding UTF-8)
=cut

POD Examples

Consider the following simple POD:

=head1 NAME

My::Module - A sample module for demonstration

=head1 SYNOPSIS

  use My::Module;
  my $obj = My::Module->new();
  $obj->do_something();

=head1 DESCRIPTION

This module provides a C<do_something()> method just for fun.
It's B<boldly> going nowhere.

=cut

You can view this documentation using perldoc your_script.pl. To convert it to HTML, you might use perldoc -o html your_script.pl or a CPAN module like Pod::Simple::HTML programmatically.

Example of a list and embedded HTML (though embedding HTML directly is less common now, often handled by the POD-to-HTML converter):

=head2 An Example List

=over 4

=item *

This is a bulleted list item.

=item *

Here's another item.

=back

=begin html

<p>This is an <em>HTML</em> block. POD parsers targeting non-HTML formats will typically ignore this.</p>

=end html

=cut

When converted to HTML, this would produce a heading, a bulleted list, and the raw HTML paragraph. Modern POD processors offer robust HTML generation without needing explicit =begin html for most common formatting.

For more comprehensive information on POD, refer to the official Perl documentation by typing perldoc perlpod or perldoc perlpodspec in your terminal.