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:
Commands begin with =, followed immediately by the command
identifier:
They can also be followed by text:=cut
A blank line signals the end of the command.=head2 Second-level head
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.
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.
The following paragraph tags are recognized as valid pod commands:
In addition to the paragraph tags, pod has a set of tags that apply within text, either in a paragraph or a command. These interior sequences are:
| Sequence | Function | ||
|---|---|---|---|
B<text> | Makes text bold, usually for switches and programs | ||
C<code> | Literal code | ||
E<escape> | Named character: E<gt> | ||
| <gt> | Literal > | ||
E<lt> | Literal < | ||
E< | Non-numeric HTML entity | ||
E< | Character number | ||
F<file> | Filename | ||
I< | Italicize | ||
Link (cross-reference) to | L< | ||
Manpage L< | Item in a manpage | ||
L< | Section in another manpage | ||
L<"sec"> | Section in this manpage; quotes are optional | ||
L< | Same as L< | ||
S< | text has non-breaking spaces | ||
X< | Index entry | ||
Z<> | Zero-width character | ||
As mentioned earlier, a number of utility programs have been written to convert files from pod to a variety of output formats. Some of the utilities are described here, particularly those that are part of the Perl distribution. Other programs are available on CPAN.