Chapter 14. 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 show some of the most used features of Pod, how to test my Pod, and how to create my own Pod translator.
The Pod Format
Sean Burke, the person responsible for most of what I’ll cover in this chapter, completely specified the Pod format in perlpodspec. 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 on the higher-level perlpod documentation page.
Pod directives start at the beginning of a line at any point where Perl
is expecting a new statement. Each directive starts with an equals 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 =encoding utf8 =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";
My Pod doesn’t have to show up in ...