Mastering Perl

Chapter 15. Working with Pod

Perl has a default documentation format called Plain Old Documentation, or Pod for short. I can use it directly in my programs, and even between segments of code. Other programs can easily pick out the Pod and translate it into more familiar formats, such as HTML, text, or even PDF. I’ll discuss some of the most used features of Pod, how to test your Pod, and how to create your own Pod translator.

The Pod Format

Sean Burke, the same person responsible for most of what I’ll cover in this chapter, completely specified the Pod format in the perlpodspec documentation page. This is the gory-details version of the specification and how to parse it, which we’ll do in this chapter. The stuff we showed you in Learning Perl and Intermediate Perl are just the basics covered in the higher-level perlpod documentation page.

Directives

Pod directives start at the beginning of a line at any point where Perl is expecting a new statement. Each directive starts with an equal sign, =, at the beginning of a line when Perl is expecting a new statement (so not in the middle of statements). When Perl is trying to parse a new statement but sees that =, it switches to parsing Pod. Perl continues to parse the Pod until it reaches the =cut directive or the end of the file:

#!/usr/bin/perl

=head1 First level heading

Here's a line of code that won't execute:

        print "How'd you see this!?\n";

=over 4

=item First item

=item Second item

=back

=cut

print "This line executes\n";

Body Elements ...