POD (Plain Old Documentation)

Perl uses a documentation format called POD (Plain Old Documentation). POD enables you to put the documentation for a program in the program itself. The system was designed to be simple and easy to use so that writing documentation would be easy.

The simplicity also makes it possible for people to create a wide variety of POD converters (pod2html, pod2man, pod2tex), which convert POD format documents into something more readable.

Documenting a Program

Suppose that you have written a program that converts US dollars to Hong Kong (HK) dollars, and you want to document it. You can do so by embedding POD documentation in the Perl script itself.

POD documentation begins with a line =pod and ends with =cut. Anything between the =pod or other POD directive and =cut lines is considered a comment by Perl but is considered documentation by the POD tools.

Start the script with the usual stuff, put in the POD documentation, and then follow this with the rest of the program. An abbreviated version of the program looks like this:

use strict; 
use warnings; 

=pod 
The pod documentation (to be done) 
=cut 
# The rest of the script 
print "This program solves all the worlds problems.
";

Now all you have to do is put something between these two directives.

A semistandard style has developed over the years when it comes to documenting programs. This style was started by the UNIX man pages and copied into the Perl documentation system. You don’t have to follow this standard, but it is the one that everyone has come to expect, and the one that’s documented here.

NAME

The first section of the documentation is the NAME section. In it, you give the name of your program and a short one-line description of what it does.

In the case of the money conversion program, this looks like

=head1 NAME 

us2hk – Convert US$ to HK$ (or vice versa)

The =head1 directive tells POD that this is a level 1 heading. The text NAME will be printed in big bold letters in the typeset of the documentation. Other levels of heading from (=head2) to (=head6) are available for your needs.

A blank line occurs after the =head1 directive. POD uses blank lines to separate things. In this case, you are separating the heading from the paragraph that follows.

This paragraph is actually a single line listing the name of the program (us2hk) and a single line description. (It’s a very short paragraph.)

POD considers text that begins in column 1 to be a part of a paragraph that can be typeset. Paragraphs are separated by blank lines.

SYNOPSIS

The SYNOPSIS section lists the program name and all the options and other arguments that can be passed to it. The SYNOPSIS section looks like

=head1 SYNOPSIS 

    us2hk [–u] [–r=<rate>] <amount>

Again, this is a level 1 head (=head1). If the next line is indented with one or more spaces, POD considers it to be a code example or command, and it will be typeset in monospace courier type. Also no typesetting conversions are made on the text.

In this example, the command is us2hk. It can take a –u flag. Because this flag is in square brackets ([]), it is optional.

The second flag also is optional. It takes an argument indicated by <rate> .

Finally, the <amount> argument is not in square brackets ([]), so it is not optional.

DESCRIPTION

The DESCRIPTION section contains a description of what the program does.

This can run for several paragraphs:

=head1 DESCRIPTION 

The I<us2hk> converts United States 
dollars to Hong Kong dollars.   It can optionally 
convert form HK to US as well. 

It is an extremely useful program if 
you ever go to Hong Kong and find out 
that a copy of Microsoft Windows 2000 
that you need to purchase is selling 
for $1600.00 (HK).

This section has two paragraphs. They are separated by a blank line. The paragraphs are not indented because POD considers indented text a code example, not a paragraph.

The first paragraph uses the I<...> escape. This tells POD to turn the enclosed text into italics. The other font controls include B<...> for bold and C<...> for code. The online document perlpod contains a complete list of escapes.

OPTIONS

Next you need to document the list of options. A list in POD starts with the following directive:

=over 4

The number 4 is the number of spaces to be used for indenting the list. Each item in the list is identified by an item directive:

=item <text>

Finally, the list is ended with the following directive:

=back

The option list looks like this:

=head1 OPTIONS 

The I<us2hk> command takes the following arguments: 

=over 4 

=item B<–u> 

Convert from US$ to HK$.  The default is HK$–E<gt>US$. 
=item B<–r=>I<rate> 

Specify the conversion rate for US$ to HK$ instead of the default: 0.128.  (1:8) 


=back

This example has a problem with the explanation of the –u option. You want to say “The default is HK$->US$.” But the greater than (>) is a special character, and you can’t put it in the text. So you must use the escape code: E<character>, which enables you to put special characters in the text.

Table 10.1 lists the escape characters.

SEE ALSO

Finally, you have the SEE ALSO section, which provides a recommended reading list to users:

=head1 SEE ALSO 

L<units>

The L<...> escape tells POD that the enclosed text is a link. This is the proper way of representing the name of another documentation. The POD translators (see “Turning POD into Something Readable”) translate a link into the appropriate value of the resulting document format.

Checking the Results

To make sure that you have done a good job on your POD documentation, you can use the command podchecker to check the POD documentation for errors:

podchecker us2hk.pl

Finally, you can view the results with the perldoc command:

perldoc us2hk

Putting It All Together

Listing 10.1 contains the complete POD documentation for the function.

Listing 10.1. us2hk.pl

=head1 NAME 

us2hk – Convert US$ to HK$ (or vice versa) 

=head1 SYNOPSIS 

    us2hk [–u] [–r=<rate>] <amount> 

=head1 DESCRIPTION 

The I<us2hk> command converts United States dollars to 
Hong Kong dollars.   It 
can optionally convert from HK to US as well. 

It is an extremely useful program if you ever 
go to Hong Kong and find 
that a copy of Microsoft Windows 2000 that 
you need to purchase is selling 
for $1600.00 (HK).   
=head1 OPTIONS 

The I<us2hk> command takes the following arguments: 

=over 4 

=item B<–u> 

Convert from US$ to HK$.  The default is HK$–E<gt>US$. 

=item B<–r=>I<rate> 

Specify the conversion rate for US$ to HK$ instead of the default: 0.128 (1:8). 

=back 

=head1 SEE ALSO 

L<units>

Figure 10.1 shows the printed copy of this documentation.