Writing and Formmating UNIX Manual Pages with -man macros

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.
Three names for regular, boring, paragraph breaks.
.TP columns
Term Paragraph. columns is optional, defaults to around 10 chars. does an item in a:
	term  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
Starts a paragraph with a hanging indent, lines after the first are indented.
Defines an indented region.
sets tabs every 0.5 inches.
These are defined in the GNU -man macros. I don't know what they do.

Generic nroff commands

verbatim stuff
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 - - - - - - - - - - - - - - - - - 
sillycommand - do something silly
.B sillycommand [options] 
.I option option
.B ["
.I f1 f2
.B  ..."]
.I sillycommand
is a shell script which does silly things, and takes some options:
.TP 5
is one option
is another option
This is another paragraph with an example:

sillycommand "with option"

.I -r
makes the command really silly.
.I -n
means the command should print the silliness, but not
actually do it.
Marc Mengel
stupid(1), bogus(2)
Mostly ridiculous.
- - - - - - - - - - - - - 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.

This Copy

I copied this Linux Man Page notes page to my site with:
curl http://www-oss.fnal.gov/~mengel/man_page_notes.html | \
sed -e 's|<h3>\(.*\)</h3>|<h2>\1</h2>|g' \
> /var/www/html/Public/Content/z/About/man_page_notes.html
and then added this block. My wrapper script applies the cascading style sheet to the page and adds the menu bar.
45 visits (1 today, 1 this week, 13 this month, 45 this year)
Uptime: 17:46:38 up 6 days, 21:29, 0 users, load average: 0.00, 0.00, 0.00 GET from server z.lam1.us

Monday, September 25, 2023 @ 5:46:38 PM