=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.