Home > Articles > Web Development > Perl

Modules in Perl

  • Print
  • + Share This
This chapter is from the book

This chapter is from the book

6.5 Documenting modules with POD

Perl documentation is generally well written and complete. This is partly because of POD, the "plain old documentation" format that allows documentation to be interspersed in Perl modules. POD can be read by a number of different programs, including several that come with Perl—perldoc , pod2html (for HTML output), pod2latex (for L ATEX output), and pod2man (for Unix-style man pages).

6.5.1 POD definitions

POD directives are placed directly inside of a Perl module. POD recognizes three kinds of lines:

  • Regular lines of text are kept verbatim.

  • Indented lines of text are kept verbatim, but indented.

  • POD commands begin in the first column, and with an equals sign (=). This is how Perl distinguishes between code and documentation.

Each POD command typically affects a single paragraph of text. For example:

package Howdy; 

-head1 NAME

   Howdy - A module for testing cowboy-speak


   This module allows programs to display error messages 
   in cowboy-speak, as well as plain ol' English.

   If you want to know what to say when tipping your 10-gallon hat, 
   you can use this module. 


This module consists entirely of a package statement and POD documentation. POD's =head1 command introduces a first-class headline, and is used for the highest-level section headings. (There is a similar =head2 command for smaller headlines.) Headline text in =head1 sections is traditionally capitalized.

6.5.2 Writing and reading POD

The =cut command ends a section of POD. If the module contains several POD sections, it may contain several =cut commands. For example, the following module has three POD sections, each of which ends with =cut:

package PodTest; 

=head1 NAME 

    PodTest - Demonstrates POD module

=head1 SYNOPSIS 

    use PodTest; 
    my $variable = $PodTest::a;


     This module demonstrates how to write POD documentation. It doesn't 
     do anything else. If you use this module, you deserve 
     what you get.


use vars qw($a $b $c); 

$a = 1; 
$b = 2; 
$c = 3; 

=head2 $a 

     The C<$a> variable contains 1. 

=head2 $b 

     The C<$b> variable contains 2.


sub return_five 
     return 5; 


=head2 return_five

     The subroutine C<return_five> returns C<5>.


The above module demonstrates single-letter POD commands, such as C and I, which modify the way in which a particular letter or word is displayed. C treats the text between < and > as literal code, I italicizes it, and B (not shown in the preceding example) makes it bold. Variable, subroutine, and module names are typically displayed using C<>.

Another useful single-letter command is L, which creates a link to another file, document, or section of a manual page. perldoc , which comes with Perl, is the easiest way to read POD documentation. Typing perldoc Module will look for that module in @INC , displaying its POD documentation. If the module does not exist, perldoc exits with an error message.

  • + Share This
  • 🔖 Save To Your Account