Programming Perl, 4th Edition

Command Paragraphs

All pod directives start with = followed by an identifier. This may be followed by any amount of arbitrary text that the directive can use however it pleases. The only syntactic requirement is that the text must all be one paragraph. Currently recognized directives (sometimes called pod commands) are:

=encoding

By default, the Pod translators assume that your Pod source is either ASCII or Latin-1. You can change this by specifying the encoding with this command, probably to UTF-8:

=encoding uft8

=head1

=head2

The =head1, =head2,… directives produce headings at the level specified. The rest of the text in the paragraph is treated as the heading description. These are similar to the .SH and .SS section and subsection headers in man(7), or to <H1>…</H1> and <H2>…</H2> tags in HTML. In fact, that’s exactly what those translators convert these directives into for those formats.

=cut

The =cut directive indicates the end of a stretch of pod. (There might be more pod later in the document, but if so it will be introduced with another pod directive.)

=pod

The =pod directive does nothing beyond telling the compiler to lay off parsing code through the next =cut. It’s useful for adding another paragraph to the document if you’re mixing up code and pod a lot.

=over NUMBER

=item SYMBOL

=back

The =over directive starts a section specifically for the generation of a list using the =item directive. At the end of your list, use =back to end it. The NUMBER, if provided, hints to the formatter ...