126 lines
2.7 KiB
Text
126 lines
2.7 KiB
Text
=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.
|