How to Write a Man Page

Introduction

Background

Finding man Pages

The -M option of the man command can be used to specify a directory to be searched instead of using the MANPATH. The -M option is especially useful for testing a new man page you are writing. For example, you could create the subdirectories man, man/man1, and man/man3 in a project directory and put the man page for a new command in man/man1/xxx.1 and the man page for a new library function in man/man3/yyy.3. Then, from the project directory the command "man -M ./man xxx" would display the man page for your xxx command and the command "man -M ./man yyy" would display the man page for your yyy library function. (Not all projects for this course involve writing both commands and library functions; write just the pages that are assigned.)

Man pages are text files, and whatever you put in them will be displayed by the man command. But to get them to look like "real" man pages, they have to be written in a special way, which brings us to the next topic: Text Processing on Unix systems.

Unix Text Processing

There are many programs that perform text formatting on Unix systems. Most operate as filters that read ASCII characters from stdin, modify the text layout, and write formatted text to stdout. The man(1) command itself sets up a pipeline to pass an ASCII man page (such as xxx.1) through a series of these filters, which do such things as format paragraphs to fit on the page properly, indent headings and sub-headings properly, and even to do such things as formatting tables and equations that might be embedded in the document. The crucial point is that the final appearance of a page is controlled by commands that are embedded in your text file, not by the way you type the original text. For example, a basic command is ".P" which marks the beginning of a paragraph. (All commands start with a dot in the first column of a line.) Once you type a .P command, whatever you type, until the next command, will be formatted into a nice paragraph with standard margins and spacing. You can type each word of the paragraph on a separate line or 100 words per line, and the paragraph will end up looking the same way. The only way you can mess up the format of a paragraph is to type extra blanks, which don't get squeezed out for you.

There is a special set of text formatting commands that you use to write man pages. You can use others as well, but the following list is all you need.

Commands for Formatting man Pages

.\" text

This is how you put comments in a man page. The text, text, is not seen by the person using man to read the page. The backslash (\) is an escape character that tells parts of the man system to treat the next character as a literal rather than as the beginning of a quoted string. Any time you have trouble putting a special character in a man page, you should try preceding it with a backslash.

To adhere to the Coding Guidelines for this course, you must document your man pages just as you document your source code. The first few lines of your man pages will start with something like this, assuming you are using RCS to manage the versions of your project:

    .\"   $Id$
    .\"
    .\"   Man page for the xyz project.
    .\"
    .\"   $Log$
    .\"

.TH name section center-footer left-footer center-header

This command normally goes on the first line after the initial block of comments of a man page file; it is used to set the title, header, and footer lines. The strings following .TH are used for the following information:

name

The name of the command or function.

section

The section of the manual. (1 for commands, etc.)

center-footer

The date the man page was last modified. Some systems do not display footers when you use the man command interactively, only when printing the pages.

left-footer

Bottom left footer. See Below

center-header

The main page (center) heading. See below.

Use quotes if any of these fields contains embedded blanks. Use "CS-701" as the left-footer for the man pages you write for this course. The main page (center) heading gives the place or organization where the software being documented originated; we'll use "Queens College."

Here is an example:

.TH mycommand 1 "December 2001" "CS-701" "Queens College"

.SH t

This command creates a section heading. The string t will appear at the left margin. The conventional section headings are NAME, SYNOPSIS, DESCRIPTION, OPTIONS, DIAGNOSTICS, and BUGS in that order. Look at existing man pages for the type of information to put in each section. The Section 5 or 7 man page for man gives guidelines too.

For projects that are done as a sequence of steps, add another section heading, VERSION, with the RCS $Revision$ keyword as the section body.

.SS t

This command creates a sub-heading. It will be indented 5 spaces from the left margin. You usually capitalize just the first letter in the words of a sub-heading.

.P

Start a new paragraph. You start the text on the next line after the .P command. Note: You must type each line of the paragraph starting in column 1 for .P to work. If you indent any lines yourself, .P will display the line as you typed it. Also, the .TH command must be present for the paragraph margins to be set properly.

.HP

Start a paragraph with a hanging indent. If the paragraph is more than one line long, the second and succeeding lines will be indented 5 spaces more than the first line.

.RS

.RE

Start and end a nested indentation. If the current indent is 5, the .RS will make it 10. If the current indent is 10, .RS will make it 15, etc.

.I t

Italics (underline) text. If you want to italicize just one word, omit t from the .I command line, and type the word on the next line. For example:

.P
This is a sentence in which the word
.I
word
is italicized.  Note that using .I does not affect the paragraph
formatting.

Would be output something like this:

     This is a  sentence in which the word word is
     italicized.  Note that using .I does not affect
     the paragraph formatting.

.B t

Like .I, but for boldface text. Often shows up as reverse video or color on CRTs.

Summary