114 lines
2.9 KiB
Text
114 lines
2.9 KiB
Text
.\" In .TH, FOO should be all caps, SECTION should be 1-8, maybe w/ subsection
|
|
.\" other parameters are allowed: see man(7), man(1)
|
|
.\"
|
|
.\" This template provided by Tom Christiansen <tchrist@jhereg.perl.com>.
|
|
.\"
|
|
.TH FOO SECTION
|
|
.SH NAME
|
|
foo, bar \- programs to do something
|
|
.SH SYNOPSIS
|
|
A short usage summary.
|
|
.PP
|
|
.B foo
|
|
{
|
|
.BR this | that
|
|
}
|
|
[
|
|
.B -flags
|
|
]
|
|
[
|
|
.B \-o
|
|
.I option
|
|
]
|
|
.I argument
|
|
[
|
|
.I more...
|
|
]
|
|
.SH DESCRIPTION
|
|
.\" Putting a newline after each sentence can generate better output.
|
|
Long drawn-out discussion of the program.
|
|
It's a good idea to break this up into subsections using the .SS macro,
|
|
like these:
|
|
.SS "A Sample Subsection"
|
|
.SS "Yet Another Sample Subsection"
|
|
References to the
|
|
.BR foo (SECTION)
|
|
(or other) manual page should use the .BR macro as here.
|
|
.PP
|
|
Use the .PP macro to start a new paragraph within a section.
|
|
.SH OPTIONS
|
|
Some people make this separate from the description.
|
|
The following style is typically used to document options:
|
|
.TP
|
|
.BR this | 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).
|
|
.TP
|
|
.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.
|
|
.IP
|
|
Use \(oq\e-\(cq rather than \(oq-\(cq for dashes in command-line options.
|
|
\(oq-\(cq means hyphen, and formats differently when using certain output
|
|
devices.
|
|
.TP
|
|
.I argument
|
|
The last
|
|
.I argument
|
|
is required, because it is not in brackets.
|
|
.TP
|
|
.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.
|
|
.SH "RETURN VALUE"
|
|
What the program or function returns if successful.
|
|
.SH ERRORS
|
|
Return codes, either exit status or errno settings.
|
|
.SH EXAMPLES
|
|
Give some example uses of the program.
|
|
.SH ENVIRONMENT
|
|
Environment variables this program might care about.
|
|
.SH FILES
|
|
All files used by the program.
|
|
Typical usage is like this:
|
|
.br
|
|
.nf
|
|
.\" set tabstop to longest possible filename, plus a wee bit
|
|
.ta \w'/usr/lib/perl/getopts.pl 'u
|
|
\fI/usr/man\fR default man tree
|
|
\fI/usr/man/man*/*.*\fR unformatted (nroff source) man pages
|
|
.SH NOTES
|
|
Miscellaneous commentary.
|
|
.SH CAVEATS
|
|
Things to take special care with, sometimes called WARNINGS.
|
|
.SH DIAGNOSTICS
|
|
All the possible error messages the program can print out,
|
|
what they mean, and how to correct them if applicable.
|
|
.SH BUGS
|
|
Things that are broken or just don't work quite right.
|
|
.SH RESTRICTIONS
|
|
Bugs you don't plan to fix. :-)
|
|
.SH AUTHOR
|
|
Who wrote it (or AUTHORS if multiple).
|
|
.SH HISTORY
|
|
Programs derived from other sources sometimes have this.
|
|
.SH "SEE ALSO"
|
|
.\" Always quote multiple words for .SH
|
|
Other man pages to check out, like
|
|
.BR man (1),
|
|
.BR man (7),
|
|
.BR mandb (8),
|
|
.BR catman (8).
|