Program PODs

The documentation for Perl programs is written in a simple markup language called POD (Plain Old Documentation).

This page shows how to write a POD for a Perl program. If you adhere to this style, then it will be easier for others to read and understand your documentation.

Read the PODs in existing programs for additional examples. 

=head1 NAME

circle - draws a circle on the screen
The NAME section gives the name of the program and a one-line description.

The name and description are separated by a dash. It is important to adhere to this format so that the POD can be converted to a proper man page.

=head1 SYNOPSIS B<circle> [B<-c> I<color>] [B<-M>] I<radius> The SYNOPSIS section shows how to run the program from the command line.

Literal text, such as the program name, is formatted in bold face (B<>). Text that the user supplies is formatted in italic (I<>). Optional items are enclosed in square brackets ([]). An ellipsis (...) indicates that an item may be repeated.

The synopsis must not be indented, so that the B<> and I<> markups will work.

=head1 DESCRIPTION B<circle> draws a circle in the center of the screen with the specified I<radius>. By default, the circle is drawn in black; a different color may be specified with B<-c>. This is a description of the program.

It should be written in terms that are relevant to the user, rather than the programmer.

  • What does it do for the user?
  • How do you use it?
  • What files does it read and write?
  • What assumptions does it make?
=head1 OPTIONS =over 4 =item B<-c> I<color> Draw the circle in I<color>. =item B<-M> print man page =back The OPTIONS section lists and describes all the command-line options that the program takes. 
=head1 FILES

=over 4

=back
The FILES section lists all the files that the program reads or writes. It may be omitted if there are none. 
=head1 DIAGNOSTICS

=over 4

=item Can't open %s: %s

(F) The file wasn't available 
for the given reason.

=back
The DIAGNOSTICS section gives the text of every error message the the program may issue, and explains its meaning.

Error messages are classified as follows:

(W)
A warning (optional)
(D)
A deprecation (optional)
(S)
A severe warning (mandatory)
(F)
A fatal error (trappable)
(X)
A very fatal error (non-trappable) 
=head1 REQUIRES

Perl 5.004, Getopt::Std, Pod::Usage
The REQUIRES section tells the user what they will need in order to run the program. 
=head1 SEE ALSO

perl(1), square(1)
This is the usual list of related programs and modules. 
=head1 AUTHOR

A. U. Thor, a.u.thor@a.galaxy.far.far.away
You should include your name and email address, in case anyone needs to contact you regarding the program. 
=cut
The =cut line denotes the end of POD text.

Some people distribute POD sections throughout their source code. Perl recognizes the POD sections and ignores them.

Steven W. McDougall / resume / swmcd@theworld.com / 2007 March 14