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.