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.

Paragraph tags

The following paragraph tags are recognized as valid pod commands:

Interior sequences

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:

SequenceFunction
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<html>  Non-numeric HTML entity
  E<n>  

Character number n, usually an ASCII character

F< file > Filename
I<text>

Italicize text, usually for emphasis or variables L<name>

Link (cross-reference) to name:

 L<name>
 Manpage L<name/ident>  Item in a manpage
  L<name/"sec">  Section in another manpage
  L< "sec" >  Section in this manpage; quotes are optional
  L</"sec">  Same as L<"sec">
S<text> text has non-breaking spaces
X<index> Index entry
Z<> Zero-width character

Pod Utilities

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.

Get Perl in a Nutshell now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial