Writing Man Pages with groff

Writing Man Pages with groff

Before the days of graphical interfaces, typesetting with the computer meant preparing a text file containing embedded typesetting commands and then processing that marked-up text file with a computer program that generated commands for the output device: a printer or some other typesetter.

As you know, such markup languages still exist. A prime example is HyperText Markup Language (HTML), which you use to prepare World Wide Web pages.

In the late 1970s and early 1980s, I prepared all my correspondence and reports on a DEC VAX/VMS system, using a program named RUNOFF. That program formatted output for a line printer or a daisy-wheel printer. That VAX/VMS RUNOFF program accepted embedded commands such as the following:

.page size 58,80
.spacing 2
.no autojustify

As you may guess, the first command sets the number of lines per page and the number of characters on each line. The second command generates double-spaced output. The last command turns off justification. Essentially, I’d pepper a text file with these commands, run it through RUNOFF, and send RUNOFF’s output to the line printer. The resulting output looked as good as a typewritten document, which was good enough for most work in those days.

UNIX came with a more advanced typesetting program called troff (which stands for typesetting runoff) that could send output to a special device called a typesetter. A typesetter could produce much better output than a line printer. troff enables you to choose different fonts and to print text in bold and italic.

To handle output on simpler printers, UNIX also included nroff (which stands for nontypesetting runoff) to process troff files and generate output, to ignore fancy output commands, and to generate output on a line printer. troff typesetting is versatile enough that many computer books were typeset by using troff.

Now that nearly every computer offers some sort of graphical interface (Microsoft Windows, Apple Macintosh, or GNOME and KDE in Linux), most word-processing programs work in WYSIWYG (what you see is what you get) mode, in which you get to work directly with the formatted document. You probably don’t have any reason, therefore, to use troff for typesetting. You still use nroff for one important task, however: preparing man pages. The remainder of this chapter focuses on that aspect of using nroff.

Insider Insight 

The groff program is the GNU version of troff and nroff. By using appropriate flags, you can use groff to typeset for several output devices, including any typewriter-like device.

Even if you don’t use groff to prepare formatted documents (because using a PC-based word processor is more convenient), you may end up using groff to write the man page for any program that you write.

Man pages are the files that contain the information that users can view by typing the command man progname. This command shows online Help information on progname. The subject of a man page can be anything from an overview of a software package to the programming information for a specific C function. (Try typing man fopen, for example, on your Linux system.)

After you go through an example, you realize that writing man pages in groff is quite simple.


Before reading about the man page preparation process, understand that you don’t really use the groff program to prepare the man page. The man page is just a text file containing embedded commands that groff recognizes. You may use groff to view a man page during preparation, but you can prepare a man page without ever running groff.

Trying an Existing man Page

Before you write a man page, look at an existing man page. A brief example is the man page for zless. Figure 11-5 shows the man page for zless in a terminal window.

Click To expand
Figure 11-5: Output of the man zless Command in a Terminal Window.

Returning to the example of the man page for the zless command, you don’t really need to pay attention to the exact content of the man page; all you care about is the layout. Take a moment to look at the layout and notice the following points:

  • The name of the command appears at the top of the man page. The number 1 that appears in parentheses next to the command’s name denotes the section of the UNIX manual where this command belongs.

  • The man page contains several sections, each of which appears in boldface. The text within the section is indented.

  • In this example, the sections are NAME, SYNOPSIS, DESCRIPTION, and SEE ALSO. If you try a few more man pages, you see that some man pages have many more sections. Almost all man pages, however, have these four sections.

  • Some text appears in boldface.

Looking at a man Page Source

After you view a man page by using the man command, you should look at the original source file from which the man command generates the output. In your Linux system, the man page source files are in several directories. The /etc/man.config file defines these directory names.

The source file for the zless man page is /usr/share/man/man1/zless.1.gz. Look at this file to see how the man page appears in its final form, which is shown in Figure 11-5. Here is how to look at the source file for the zless man page:

zless /usr/share/man/man1/zless.1
zless \- file perusal filter for crt viewing of compressed text
.B zless
[ name ...  ]
.I  Zless
is a filter which allows examination of compressed or plain text files
one screenful at a time on a soft-copy terminal.  It is the equivalent of
setting the environment variable PAGER to
.I less,
and then running zmore.  However, enough people seem to think that having the
.I zless
available is important to be worth providing it.
zmore(1), less(1)

One interesting feature of the marked-up text file for the man page is the haphazard manner in which lines break. The formatting program groff (the man command uses groff to process the marked-up text file) fills up the lines of text and makes everything presentable.

Most groff commands must appear on a line by themselves, and each such command starts with a period or a dot. You can, however, embed some groff font-control commands in the text; these embedded commands start with a backslash (\).

Following is a summary of the commands that you see in the zless man page source file:

  • .B turns on boldface.

  • .I turns on italic.

  • .SH is the start of a new section.

  • .TH indicates the document title.

If you use these dot commands (meaning commands that begin with a period or dot) to change the font, the man page source file tends to display many short lines, because each dot command must appear on a separate line. As the following section shows, you can use embedded font-change commands to produce a more readable source file.

Writing a Sample man Page

This section shows you how to write a man page for a sample application by the name of satview. Assume that the satview program displays a satellite image in a window. The program includes some options for specifying the map projection, the zoom level, and the name of the file that contains the satellite image data.

Use a text editor to type the man page source code shown in the following listing and save it in a file named satview.1:

.TH SATVIEW 1 "April 19, 2003" "Satview Version 10.1"
satview \- View satellite images.
\fBsatview\fP [-p \fIprojection\fP] [-m] [-z \fIzoomlevel\fP]
\fBsatview\fP displays the satellite image from \fIfilename\fP.
.SS Options
\fB-p \fIprojection\fR
Set the map projection (can be \fBL\fR for Lambert Conformal or
\fBP\fR for Polar Stereographic). The default is Lambert Conformal.
Include a map in the satellite image.
\fB-z \fIzoomlevel\fR
Set the zoom level (can be one of: 2, 4, or 8). The default
zoomlevel is 1.
File containing satellite data.
Initialization commands for \fBsatview\fR
nexrad(1), contour(1)
.SH Bugs
At zoom levels greater than 2, map is not properly 
aligned with image.

With this information in hand, you should understand the man page source listing.

Testing and Installing the man Page

As you prepare the man page file, you want to make sure that it’s formatted correctly. To view the formatted output, use the following command:

groff -Tascii -man satview.1 | more

This command runs the groff command with the ascii typesetting device (which means that it produces plain ASCII output) and with the man page macro set (that’s what the -man option does).

If you find any formatting discrepancies, check the dot commands and any embedded font-change commands, and make sure that everything looks right.

After you’re satisfied with the man page format, you can make the man page available to everyone by copying the file to one of the directories in which all man pages reside. Log in as root and install the man page by using the following copy command:

cp satview.1 /usr/share/man/man1

After that, try the man page by using this command:

man satview

Figure 11-6 shows the resulting output. Compare the output with the source file listing shown in the preceding section, “Writing a Sample man Page,” to see the effects of the commands on the final output. The italic command generates underlined output, because the terminal window can’t display an italic font.

Click To expand
Figure 11-6: Output of the man satview Command in a Terminal Window.

Using the listing in this section as a guide, you can now write your own man pages.