Writing man Pages Using groff

groff is the GNU version of the popular nroff/troff text-formatting tools provided on most Unix systems. Its most common use is writing manual pages—online documentation for commands, programming interfaqces, and so forth. In this article, we show you the ropes of writing your own man pages with groff.

Two of the original text processing
systems found on Unix systems are troff and nroff, developed at
Bell Labs for the original implementation of Unix (in fact, the
development of Unix itself was spurred, in part, to support such a
text-processing system). The first version of this text processor
was called roff (for “runoff”);
later came troff, which generated output for a particular
typesetter in use at the time. nroff was a later version that
became the standard text processor on Unix systems everywhere.
groff is GNU's implementation of nroff and troff that is used on
Linux systems. It includes several extended features and drivers
for a number of printing devices.

groff is capable of
producing documents, articles, and books, much in the same vein as
other text-formatting systems, such as TeX. However, groff (as well
as the original nroff) has one intrinsic feature that is absent
from TeX and variants: the ability to produce plain-ASCII output.
While other systems are great for producing documents to be
printed, groff is able to produce plain ASCII to be viewed online
(or printed directly as plain text on even the simplest of
printers). If you're going to be producing documentation to be
viewed online, as well as in printed form, groff may be the way to
go (although there are alternatives, such as Texinfo, Lametex, and
other tools).

groff also has the benefit
of being much smaller than TeX; it requires fewer support files and
executables than even a minimal TeX distribution.

One special application of groff is to format Unix man pages.
If you're a Unix programmer, you'll eventually need to write and
produce man pages of some kind. In this article, we'll introduce
the use of groff through the writing of a short man page.

As with TeX, groff uses a particular text-formatting language
to describe how to process the text. This language is slightly more
cryptic than systems such as TeX, but also less verbose. In
addition, groff provides several macro packages that are used on
top of the basic formatter; these macro packages are tailored to a
particular type of document. For example, the
mgs macros are an ideal choice for
writing articles and papers, while the
man macros are used for man
pages.

Writing a man Page

Writing man pages with groff is actually quite simple. For
your man page to look like others, you need to follow several
conventions in the source, which are presented below. In this
example, we'll write a man page for a mythical command
coffee that controls your
networked coffee machine in various ways.

Using any text editor, enter the source from Listing 1 and
save the result as coffee.man. Do not enter the
line numbers at the beginning of each line; those are used only for
reference later in the article.

Don't let the amount of obscurity in this source file
frighten you. It helps to know that the character sequences
\fB, \fI, and
\fR are used to change the font to boldface,
italics, and roman type, respectively. \fP sets
the font to the one previously selected.

Other groff requests appear on lines beginning with a dot
(.). On line 1, we see that the
.TH request is used to set the title of the man
page to COFFEE, the man section to
1, and the date of the last man page revision.
(Recall that man section 1 is used for user commands, section 2 is
for system calls, and so forth. The man man
command details each section number.) On line 2, the
.SH request is used to start a section, entitled
NAME. Note that almost all Unix man pages use
the section progression NAME,
SYNOPSIS, DESCRIPTION,
FILES, SEE ALSO,
NOTES, AUTHOR, and
BUGS, with extra, optional sections as needed.
This is just a convention used when writing man pages and isn't
enforced by the software at all.

Line 3 gives the name of the command and a short description,
after a dash ([mi]). You should use this format
for the NAME section so that your man page can
be added to the whatis database
used by the man -k and
apropos commands.

On lines 4—6 we give the synopsis of the command syntax for
coffee. Note that italic type
\fI...\fP is used to denote
parameters on the command line, and that optional arguments are
enclosed in square brackets.

Lines 7—12 give a brief description of the command. Boldface
type is generally used to denote program and file names. On line
13, a subsection named Options is started with
the .SS request. Following this on lines 14—25
is a list of options, presented using a tagged list. Each item in
the tagged list is marked with the .TP request;
the line after.TP is the
tag, after which follows the item text itself. For example, the
source on lines 14—16:

.TP
\fB-h\P
Brew hot coffee. Cold is the default.

will appear as the following in the output:

-h Brew hot coffee. Cold is the default.

You should document each command-line option for your program
in this way.

Lines 26—29 make up the FILES section of
the man page, which describes any files that the command might use
to do its work. A tagged list using the .TP
request is used for this as well.

On lines 30—31, the SEE ALSO section is
given, which provides cross-references to other man pages of note.
Notice that the string <\#34>SEE
ALSO<\#34> following the .SH
request on line 30 is in quotes; this is because
.SH uses the first whitespace-delimited argument
as the section title. Therefore any section titles that are more
than one word need to be enclosed in quotes to make up a single
argument. Finally, on lines 32—34, the BUGS
section is presented.

Trending Topics

Upcoming Webinar

Getting Started with DevOps - Including New Data on IT Performance from Puppet Labs 2015 State of DevOps Report

August 27, 2015
12:00 PM CDT

DevOps represents a profound change from the way most IT departments have traditionally worked: from siloed teams and high-anxiety releases to everyone collaborating on uneventful and more frequent releases of higher-quality code. It doesn't matter how large or small an organization is, or even whether it's historically slow moving or risk averse — there are ways to adopt DevOps sanely, and get measurable results in just weeks.