=head1 NAME

foo, bar - programs to do something

=head1 SYNOPSIS

A short usage summary.

B<foo> { B<this>|B<that> } [ B<-flags> ] [ B<-o> I<option> ] I<argument> [ I<more...> ]

=head1 DESCRIPTION

Long drawn-out discussion of the program. It's a good idea to break this
up into subsections using "=head2" directives, like these:

=head2 A Sample Subsection

=head2 Yet Another Sample Subsection

References to the foo(1) (or other) manual page should be written normally
as here; B<pod2man> will usually guess the correct formatting. Use S<L><>
(e.g. L<foo(SECTION)>) if you need to force this.

Paragraphs are separated by blank lines.

=head1 OPTIONS

Some people make this separate from the description.

The following style is typically used to document options:

=over 8

=item B<this>|B<that>

The user MUST specify either B<this> or B<that> to run the program. The {
and } braces mean one of the enclosed is required. The bar (|) separates
exclusive options (i.e. you cannot have both at once).

=item B<-o>

Pass the user-supplied I<option> to B<foo> to change its behaviour. The
fact that I<option> is underlined or in italics means that the user replaces
it with a valid value for this option. The [ and ] brackets mean it isn't
required.

=item I<argument>

The last I<argument> is required, because it is not in brackets.

=item I<more>

means that the user can optionally specify additional arguments at the end.
The ellipses (...) indicate one or more of this parameter is allowed.

=back

=head1 RETURN VALUE

What the program or function returns if successful.

=head1 ERRORS

Return codes, either exit status or errno settings.

=head1 EXAMPLES

Give some example uses of the program.

=head1 ENVIRONMENT

Environment variables this program might care about.

=head1 FILES

All files used by the program. Typical usage is like this:

=over 8

=item F</usr/man>

default man tree

=item F</usr/man/man*/*.*>

unformatted (nroff source) man pages

=back

=head1 NOTES

Miscellaneous commentary.

=head1 CAVEATS

Things to take special care with, sometimes called WARNINGS.

=head1 DIAGNOSTICS

All the possible error messages the program can print out, what they
mean, and how to correct them if applicable.

=head1 BUGS

Things that are broken or just don't work quite right.

=head1 RESTRICTIONS

Bugs you don't plan to fix. :-)

=head1 AUTHOR

Who wrote it (or AUTHORS if multiple).

This example was constructed by Colin Watson <S<cjwatson@debian.org>>
from a template provided by Tom Christiansen <S<tchrist@jhereg.perl.com>>.

=head1 HISTORY

Programs derived from other sources sometimes have this.

=head1 SEE ALSO

Other man pages to check out, like man(1), man(7), mandb(8), catman(8).

For this example, see pod2man(1) for more details.