FM / examples

/usr/share/doc/man-db/examples

Name	Size	Mode	Actions
manpage.example	2965	0644	edit dl rm
manpage.example.mdoc	3811	0644	edit dl rm
manpage.example.pod	2766	0644	edit dl rm
manpage.example.sgml.gz	2432	0644	edit dl rm
manpath.config.gz	1977	0644	edit dl rm

Edit: /usr/share/doc/man-db/examples/manpage.example.pod (2766B)

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

cmd: