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:
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.
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.
|Makes text bold, usually for switches and programs|
|Named character: |
|Non-numeric HTML entity|
Link (cross-reference) to
|Manpage ||Item in a manpage|
|Section in another manpage|
|Section in this manpage; quotes are optional|
|Same as |
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.