POD (Plain Old Documentation)

The perldoc program expects your documentation to be in POD format. The pod format has a few (very few) tags that you use to markup plain text. As an aside, the Perl compiler ignores POD commands so they can be used for extended comments inside your code.
Here is a list of some of the tags, with some HTML tags that are similar in spirit:

POD tag	HTML equivalent	Description
=head1	<H1>	Primary heading.
=head2	<H2>	Secondary heading.
=over N	<UL> or <OL>	Indent N spaces until it finds a =back tag. The convention is generally to indent in multiples of 4, so you see =over 4 a lot.
=back	</UL> or </OL>	Indicates that you are done with indenting.
=item	<LI>	Indicates a list item. The convention is to use =over to begin a list, and =back to end it. Generally you do =item *, which puts bullets in front of each list item.
=cut	</HTML>	Indicates the end of a POD section.

For more information on POD, type perldoc perlpod at a UNIX prompt. There's not much to POD, and it will behoove you to know it inside & out.

Example:

=head1 NAME

NewModule - Perl module for hooting

=head1 SYNOPSIS

  use NewModule;
  my $hootie = new NewModule;
  $hootie->verbose(1);
  $hootie->hoot;  # Hoots
  $hootie->verbose(0);
  $hootie->hoot;  # Doesn't hoot
  

=head1 DESCRIPTION

This module hoots when it's verbose, and doesn't do anything 
when it's not verbose.  

=head2 Methods

=over 4

=item * $object->verbose(true or false)

=item * $object->verbose()

Returns the value of the 'verbose' property.  When called with an
argument, it also sets the value of the property.  Use a true or false
Perl value, such as 1 or 0.

=item * $object->hoot()

Returns a hoot if we're supposed to be verbose.  Otherwise it returns
nothing.

=back

=head1 AUTHOR

Ken Williams (ken@mathforum.org)

=head1 COPYRIGHT

Copyright 1998 Swarthmore College.  All rights reserved.

This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 SEE ALSO

perl(1).

=cut