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

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

=over 4

=item Can't open %s: %s

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

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:

A warning (optional)
A deprecation (optional)
A severe warning (mandatory)
A fatal error (trappable)
A very fatal error (non-trappable)

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.
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 / / 2007 March 14