Writing and Formmating UNIX Manual Pages with -man macros

Manual pages are written in source form, which looks like the example below. Several simple nroff/troff macros are used from the -man macro package. Note that nroff macros which must are put with their leading dot in column 1.

Macros defined in -man

.TH name section date

specifies page headings/footings of:

+--------------------------------------------+
|name(section)			name(section)|
|                                            |
/                                            /
|                                            |
| 	    	date		page-number  |
+--------------------------------------------+

.SH "stuff"

Section heading of stuff, (quotes can be ommitted if no blanks in stuff)

.SS "stuff"

Sub-Section heading of stuff, (quotes can be ommitted if no blanks in stuff)

.B stuff

stuff in bold

.I stuff

stuff in italics

.BI a b a b a b a... .IB a b a b a b a... .RI a b a b a b a... .IR a b a b a b a... .RB a b a b a b a... .BR a b a b a b a...

BI does the a's in bold and the b's in italic, BI does vice versa, RI does the a's in regular/roman and the b's in Italic, etc.

.P .LP .PP

Three names for regular, boring, paragraph breaks.

.TP columns term paragraph...

Term Paragraph. columns is optional, defaults to around 10 chars. does an item in a:

	term  paragraph...
	      paragraph
	longterm
	      paragraph
	      paragraph

kind of list.

.IP thing

Starts an Indented paragraph (Item Paragraph?). If item is present, it is put to the left of the paragraph

.HP

Starts a paragraph with a hanging indent, lines after the first are indented.

.RS ... .RE

Defines an indented region.

.DT

sets tabs every 0.5 inches.

.SM .SB .PD

These are defined in the GNU -man macros. I don't know what they do.

Generic nroff commands

.nf verbatim stuff .fi

no-fill and fill mode, to bracket stuff you want presented as-is.

.\" stuff

comment line

Anyhow, those are the macros ones I ever use. A sample manpage follows:

- - - - - - - - - - - - - cut here - - - - - - - - - - - - - - - - - 
.TH SILLYCOMMAND 8 LOCAL
.SH NAME
sillycommand - do something silly
.SH SYNOPSIS
.B sillycommand [options] 
.I option option
.B ["
.I f1 f2
.B  ..."]
.SH DESCRIPTION
.I sillycommand
is a shell script which does silly things, and takes some options:
.TP 5
f1
is one option
.TP
f2 
is another option
.P
This is another paragraph with an example:
.br
.nf

sillycommand "with option"

.fi
.SH OPTIONS
.TP
.I -r
makes the command really silly.
.TP
.I -n
means the command should print the silliness, but not
actually do it.
.SH AUTHOR
Marc Mengel
.SH SEE ALSO
stupid(1), bogus(2)
.SH DIAGNOSTICS
Mostly ridiculous.
.SH BUGS
- - - - - - - - - - - - - cut here - - - - - - - - - - - - - - - - -

(don't forget to "setup groff")

you format 'em with

groff -man -Tascii manpage > asciioutput

for ascii formatted man pages, or with

groff -man manpage > output

for PostScript typeset pages.

You can then take the ascii formatted page and run it through

man2html -title 'manpage' < asciioutput > htmlfile

to make html out of it.

Running manpages through groff a second time looks really bad. This is usually the cause of strange looking manpages -- things are in source/unformatted manual directories that are already formatted, and then when you run "man", it tries to format them -- again! The naming differences between .../man and .../catman on many systems are important here -- catman holds preformatted pages, and man holds source pages.