4.11 Pod

Pod is a simple, but surprisingly capable, text formatter that uses tags to tell a translator how to format the text. The tags serve several purposes:

• They tell the formatter how to lay out text on the page.

• They provide font and cross-reference information.

• They start and stop parsing of code.

The last item is indicative of one of pod's most useful features; - that it can be intermixed with Perl code. While it can be difficult to force yourself to go back and write documentation for your code after the fact, with Perl you can simply intermingle the documentation with the code, and do it all at once. It also lets you use the same text as both code documentation and user documentation if you wish.

A pod translator reads a file paragraph by paragraph, ignoring text that isn't pod, and converting it to the proper format. Paragraphs are separated from each other by blank lines (not just by a newline). The various translators recognize three kinds of paragraphs:

Command

Commands begin with =, followed immediately by the command identifier:

=cut

They can also be followed by text:

=head2 Second-level head

A blank line signals the end of the command.

Text

A paragraph consisting of a block of text, generally filled and possibly justified, depending on the translator. For example, a command like =head2 is probably going to be followed with a text paragraph:

=head2 Pod

Pod is a simple, but surprisingly capable, text formatter that uses
tags to tell a translator how to format the text.

Verbatim

A paragraph that is to be reproduced as-is, with no filling or justification. To create a verbatim paragraph, indent each line of text with at least one space:

Don't fill this paragraph. It's supposed 
to look exactly like this on the page.
There are blanks at the beginning of each line.