7.1. POD Demonstration

How to write POD

POD sections start with a single POD directive on a new line and continue up to the next =cut directive also on a line of its own. Here are some POD directives:

Headers

=head1, =head2, =head3, etc. - these are headers. The lower the header number is, the more significant it is and the bigger font will be used for it. Headers are followed by the text of the header. For example:

=head1 All you wanted to know about animals.

=head2 Introduction

This document aims to explain about animals.

=head2 Mammals.

=head3 Cats

Cats are awesome. They are useful for keeping the rats' population at
bay.

=head3 Dogs

Dogs have been called Man's best friend.

Regular Text

As you can see, a regular paragraph text is a paragraph. Paragraphs are separated by blank lines, and newlines are ignored.

Code Blocks

A code block (or verbatim paragraph) can be added by creating a portion of the text that's indented by using whitespace. In code blocks, newlines are not ignored. For example:

=head1 All you wanted to know about animals.

=head2 Introduction

This document aims to explain about animals.

=head2 Mammals.

=head3 Cats

Cats are awesome. They are useful for keeping the rats' population at
bay.

=head3 Dogs

Dogs have been called Man's best friend.

Here is an example program to name your dog:

    #!/usr/bin/perl

    use strict;
    use warnings;

    my @dog_names = (qw(Rex George Beethoven Max Rocky Lucky Cody));

    print "Name your dog " . $dog_names[rand(@dog_names)] . "!\n";

Put it in a file and run it.

Formatting Codes

One can use some formatting codes:

I<text> - for italic text.
B<text> - for bold text.
C<text> - for code (monospace) text.
L<text> - hyperlinks - see perldoc perlpod for more information.
E<lt> , E<gt> , E<htmlname>, etc. are escapes.

One should note that one can combine several styles at once using BI< ... > notation. Furthermore, one can enclose text with special characters (such as < and >) using several <<< and trailing >>> characters.

Lists

One can use lists in POD by writing =over 4 (or some other value of indent-level instead of "4"), and then several =item's and finally =back. An item can be =item * for a bullet, =item 1. to produce numbered lists or =item title to produce a definition list.

For example:

=head1 All you wanted to know about animals.

=head2 Introduction

This document aims to explain about animals.

=head2 Mammals.

=head3 Cats

Cats are awesome. They are useful for keeping the rats' population at
bay.

=head3 Dogs

Dogs have been called Man's best friend.

Here is an example program to name your dog:

    #!/usr/bin/perl

    use strict;
    use warnings;

    my @dog_names = (qw(Rex George Beethoven Max Rocky Lucky Cody));

    print "Name your dog " . $dog_names[rand(@dog_names)] . "!\n";

Put it in a file and run it. This program will generate one of the following
names:

=over 4

=item * Rex

Rex like the dinosaur.

=item * George

Like George Washington.

=item * Beethoven

Last name of the famous composer.

=item * Max

Short for Maximilian.

=item * Rocky

Like the film.

=item * Lucky

A lucky dog.

=item * Cody

For good coding.

=back

For More Information

POD has some other directives. For more information refer to perldoc perlpod, and to the Wikipedia page about POD.