D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
share
/
doc
/
man-db
/
examples
/
Filename :
manpage.example.pod
back
Copy
=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.