Here's an example to produce well-formed man pages. When you
start with pod, =head1 will mean .SH, =head2 will mean .SS,
and the .TH gets handled for you automatically.
The rest should be similar.
--tom
.TH NAME SECTION
.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
.\" other parms are allowed: see man(7), man(1)
.SH NAME
foo, bar \- programs to do something
.SH SYNOPSIS
a short usage summary
.SH "DESCRIPTION"
long drawn out discussion of the program. it's a good idea
to break this up into subsections using the .SS macros, like
these:
.SS "A Sample Subection"
various bits
.SS "Yet Another Sample Subection"
diverse bits
.SH OPTIONS
Some people make this separate from the description.
.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
envariables this program might care about
.SH FILES
All files used by the program. Aypical usage is like this:
.br
.nf
.\" set tabstop to longest possible filename, plus a wee bit
.ta \w'/usr/man/man*/*.* 'u
.\" make sure these have a tab
\fI/usr/man\fR default man tree
\fI/usr/man/man*/*.*\fR unformatted (nroff source) man pages
.\" you'd better restore tabs later
.SH "SEE ALSO"
.\" Always quote multiple words for .SH
other man pages to check out, like man(1), man(7), makewhatis(8), catman(8)
.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, and
what they mean.
.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.
start with pod, =head1 will mean .SH, =head2 will mean .SS,
and the .TH gets handled for you automatically.
The rest should be similar.
--tom
.TH NAME SECTION
.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
.\" other parms are allowed: see man(7), man(1)
.SH NAME
foo, bar \- programs to do something
.SH SYNOPSIS
a short usage summary
.SH "DESCRIPTION"
long drawn out discussion of the program. it's a good idea
to break this up into subsections using the .SS macros, like
these:
.SS "A Sample Subection"
various bits
.SS "Yet Another Sample Subection"
diverse bits
.SH OPTIONS
Some people make this separate from the description.
.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
envariables this program might care about
.SH FILES
All files used by the program. Aypical usage is like this:
.br
.nf
.\" set tabstop to longest possible filename, plus a wee bit
.ta \w'/usr/man/man*/*.* 'u
.\" make sure these have a tab
\fI/usr/man\fR default man tree
\fI/usr/man/man*/*.*\fR unformatted (nroff source) man pages
.\" you'd better restore tabs later
.SH "SEE ALSO"
.\" Always quote multiple words for .SH
other man pages to check out, like man(1), man(7), makewhatis(8), catman(8)
.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, and
what they mean.
.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.