How to Write man Pages

If you are reading this you undoubtedly know what a man page is, so I won't bother to explain what they are. I'll instead go on the assumption that you are probably a consultant who got asked to write some man pages and that you'd like to know how to do that in a quick and painless fashion. A'ighty then...

First thing you've gotta do is write a man page source file. Because we don't have consultants writing man pages for libraries and similar things very often I'll assume that you are writing a man page for a user program, something that would be found in section 1 of the man pages. The first thing you need to do is write an nroff input file for the man page. Following standard naming conventions the filename for a section one source file, your source file should be named "<executable name>.1". An nroff template for a section 1 man page is given below:

.TH "<program name>" 1
.SH NAME
<program name> \- <one line description of program>
.SH SYNOPSIS
.B <program name>
<grammar for command line>
.SH DESCRIPTION
<detailed description of what the program does>
.SH OPTIONS
.TP
.B \-<a command line switch>
<description of what that switch does>
.TP
.B \-<a command line switch>
<description of what that switch does>
.TP
.B <etc . . .>
.SH "SEE ALSO"
<a list of related man pages>
.SH BUGS
<known bugs if any>
    

Once you've written your source file you need to run it through nroff to make sure it looks right. I recommend the following command line: nroff -man <source file> | less. This lets you see what it will look like when a user does a man <executable name>. In the case of the above template it should look more or less like this:

User Commands                           <program name>(1)

NAME
     <program name> - <one line description of program>

SYNOPSIS
     <program name> <grammar for command line>

DESCRIPTION
     <detailed description of what the program does>

OPTIONS
     -<a command line switch>
          <description of what that switch does>

     -<a command line switch>
          <description of what that switch does>

     <etc . . .>

SEE ALSO
     <a list of related man pages>

BUGS
     <known bugs if any>

    

When you are satisfied with what you see find a staffer and tell them you need to install a man page.

Copyright (c) HMC Computer Science Department. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License.''