POD (Plain Old Documentation) Files

POD, short for Plain Old Documentation, is a simple formatting language for creating documentation to go along with your Perl scripts or modules. Commonly, you'll embed that documentation inside your script file itself; that way you can keep both the script and the documentation together and not have to keep track of each separately (Perl will happily ignore the POD content when it executes your scripts).

To view the POD content of your script (or to view POD files containing nothing but POD content), you can use the perldoc script (part of the Perl distribution) to display that text on your screen, or you can use a translator to convert the POD files into something else—for example, pod2text for text files, pod2html for HTML, pod2man for nroff-formatted man pages, or pod2latex for LaTeX formatting. Throughout this book you've probably been using perldoc—and therefore POD files—to view the various bits of Perl documentation online.

POD is not a fully featured text-formatting language such as troff, TeX, or even HTML. If you want to create lots of heavily formatted documentation for your scripts, you'd be better off using something else and keeping your document files separate from your scripts. But POD files generally can be read on different platforms and with different systems or can be converted to other more common formats on-the-fly.

You can find examples of POD text in just about any publicly available script or module from the Perl distribution and from CPAN. More details than those in this section can also be found in the perldoc man page.

Creating POD Files

POD-formatted text consists of command paragraphs and regular paragraphs. Command paragraphs describe simple formatting and some text; regular paragraphs contain actual body text. You can also embed character-formatting commands inside regular paragraphs.

Command paragraphs appear on individual lines and begin with an equal sign. Some command paragraphs have associated text, which appears just after the name of that paragraph. The end of the command paragraph is a blank line.

For headings, use the =head1 and =head2 command paragraphs, with the text of the heading immediately following the command. These headings are similar to the <H1> and <H2> tags in HTML or the .SH tag in troff or nroff.

For lists or other indented items, use the =over, =item, and =back commands. Use =over to start a list, with an optional number indicating the number of spaces to indent the list. Each list item begins with an =item tag, with an optional character indicating the symbol or number to mark each item (you'll have to do numbering yourself; it doesn't happen automatically). And, finally, use =back to undo the indent created by the =over.

Regular paragraphs are included as simple paragraphs, typed, with no command paragraph to indicate them. Paragraphs that start without initial whitespace are typically reformatted to fit the page width (like <p> in HTML); paragraphs with initial indentation are used verbatim (like <pre> in HTML). All paragraphs must end with a blank line.

You can embed character-formatting codes and links in paragraphs to emphasize a particular word or to link to something else (commonly another Perl-related man page like perlfunc or the like). The following are some of the more common character formats:

• I<text> will italicize the word text.

• B<text> will boldface the word text.

• C<text> uses text as literal code.

• &escape; substitutes a special character for the code escape. These are nearly identical to the HTML escape codes for accents and other special characters.

• E<escape> does the same thing as &escape;.

• L<manpage> will create a link (or a textual cross-reference) to a man page, for example, L<perlfunc> links to the perlfunc man page. You can also link to specific sections in the man page itself.

To embed text formatted in some other formatting language—HTML, or troff, for example—use the =for, =begin, and =end commands. Text formatted for specific formatting languages will be output unprocessed by the specific translator (for example, the pod2html translator will copy any formatted HTML directly to the output) and will be ignored otherwise. Use embedded formatting as a way of providing conditional formatting in specific instances.

Embedding POD in Scripts

You can either include POD-formatted text in its own file (conventionally as files ending with a .pod extension), or you can include them inside your script files, making them easy to change and keep updated.

To include POD text inside a script, start it with any POD command (typically =head1, although the =pod command can indicate the start of POD text as well). End all the POD text with =cut. This will tell Perl when to stop and restart parsing the text for actual Perl code.

Although POD text is usually included as a block either at the beginning or end of a script, you can also put it anywhere inside your script, for example, to describe a subroutine's behavior next to the subroutine itself. As long as you start and end your POD text with a command paragraph and =cut, Perl won't have a problem with this.

To include POD text at the end of a file, and when you're using an __END__ marker (as you might be if you're creating modules), make sure you include a blank line after the __END__.