Writing and reading man pages

The Mechanics of Writing Man Pages

Man pages are written in a simple markup language using nroff/groff macros (Table 3). Each markup tag begins with a period and is followed by one or two letters. Typically, the markup is placed at the start of a line and continues to be in use until either the next tag or a closing parenthesis – ) – appears. One or two tags comprise pairs of starting and closing tags. Spacing on a line is handled either by tabs or by the markup's macro.

Table 3

Man Markup

Format

Description

.TH

[name of program] [section number] [center footer] [left footer] [center header] The title/header of the man page, generally written entirely in upper case. Always the first line of a man page.

.SH

[text] Section heading.

.PP

Creates a line break. Always use to leave a space, rather than leaving a line blank.

."

Comment line (for source file).

.TP

Indent the text two lines below.

.nf

Start of pre-formatted text.

.fi

End of pre-formatted text.

.RS

Start of a relative margin indent.

.RE

End of a relative margin indent.

.B

Bold weight.

.I

Italics.

/-/

A dash.

Compiling and Formatting Man Pages

Man pages are stored as bzip or gzip files. You can prepare a man page in several ways, including Perl's pod2man script. However, most methods use some variant of the troff/groff document formatting systems, which are even older than man in Unix-like systems. These commands are a subject in themselves, but using them to create man pages requires little knowledge.

Write the man page in a text editor or nroff/groff, remembering to spell check. If your editor does not support spell checking, you can copy and paste it to one that does. The first parts of the file name should be the page name, separated by a period from the man section number. As you write, you can check your formatting with the command:

nroff -man FILE | less

When you have finished entering, enter the basic command:

ngroff -man FILE > OUTPUTFILE

Compress the output file with gzip or bzip, and place the compressed file in a directory in the MANPATH environment variable. To access the new file, add it to the man database with mandb -c or, in some distributions, make what is.

You can also convert the output file to Postscript with:

groff -man -Tps FILE > FILE.ps

Similarly, the command to produce a PDF file is

groff -man -Tpdf FILE > FILE.pdf

Another option for PDF conversion is to use the command-line utility ps2pdf to produce the PDF file from the Postscript file.

Converting to HTML is even simpler. With the man2html utility installed, enter:

man2html FILE

The output is an HTML file of the same name in the output file's directory

Buy this article as PDF

Express-Checkout as PDF

Pages: 4

Price $2.95
(incl. VAT)

Buy Raspberry Pi Geek

SINGLE ISSUES
 
SUBSCRIPTIONS
 
TABLET & SMARTPHONE APPS
Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content