summaryrefslogtreecommitdiffstats
path: root/docs/manpage.example.pod
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/manpage.example.pod126
1 files changed, 126 insertions, 0 deletions
diff --git a/docs/manpage.example.pod b/docs/manpage.example.pod
new file mode 100644
index 0000000..7c62de7
--- /dev/null
+++ b/docs/manpage.example.pod
@@ -0,0 +1,126 @@
+=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.