Writing man pages

Traditional UNIX command-line utilities have always been documented in man pages. A simple man <command> will tell you how to use the command. This tutorial will give you a quick introduction to writing manual pages.

The advantage of man pages over other forms of documentation is that:

  • They can be viewed within seconds on any UNIX console or terminal.
  • They can be easily converted to other formats: Postscript, Text, PDF and even HTML (amongst others).

The Sections

Man pages are structured in sections just like a book is structured in chapters. For example, there are two man pages on printf. One for the C-library function (section 3) and the other for the shell command printf (section 1). The different sections are:

Section
1 User commands - Executable programs or shell commands
2 System calls (functions provided by the kernel)
3 Library calls (functions within program libraries)
4 Devices/Special files (usually found in /dev)
5 File formats and conventions, e.g. /etc/passwd
6 Games
7 Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
8 System administration commands (usually only for root)
9 Kernel routines [Non-standard]

Therefore typing "man 1 printf" will give you the documentation about the shell command printf and "man 3 printf" will display the description of the C-library function. Running just "man printf" will print the page that is first found (usually printf from section 1).

MANPATH

The man command searches for man pages based on the value of the environment variable MANPATH. You can add any directory to this variable and man will search for relevant man pages within it.

  • In 'sh' or 'bash', we can use:
    MANPATH=/usr/man:/usr/share/man:/usr/local/share/man:/usr/openwin/share/man
    export MANPATH
  • In 'csh' or 'tcsh':
    setenv MANPATH "/usr/man:/usr/share/man:/usr/local/share/man:/usr/openwin/share/man"

After setting the MANPATH you can try "man <command>" to see if you get one of the pages you are looking for.

Formatting keywords

Writing a man page is very simple. It uses a markup language where keywords start with a dot at the beginning of the line. These keywords are also called macros. The most important macros are:

.TH This starts the title/header of the man page
.SH Section Heading
.PP New paragraph
." Comment line
.TP Indent the text

.TH syntax

.TH [name of program] [section number] [center footer] [left footer] [center header]

.SH syntax

.SH text for a heading

.PP syntax

The syntax of .PP is very straightforward. It just causes a line break.

All formatting macros for man pages are documented in groff_man(7). The groff_man(7) page is very detailed and contains all you need to know.

Getting started

Before you start to write your own man page you should know that man pages are normally structured in chapters. By convention the possible chapter headings are as follows:

NAMEThe name of the command or function, followed by a one-line description of what it does.
SYNOPSISUsage.
DESCRIPTIONA textual description of the functioning of the command or function.
OPTIONSShould include options and parameters
RETURN VALUESSections (2) and (3) function calls
ENVIRONMENTDescribe environment variables.
FILESFiles associated with the subject
EXAMPLESCommon usage examples and suggestions.
DIAGNOSTICSNormally used for section (4) device interface diagnostics.
ERRORSSection (2) and (3) error and signal handling
STANDARDSConformance to standards if applicable.
BUGSList of known bugs, gotchas and caveats.
AUTHORAuthors contact information.
SEE ALSOCross-references and citations

Sample man page

Here is a sample man page called foo.1. Note that the \- is required to make the dash distinct from hyphens.

.TH foo 1 "April 1, 2001" "version 0.1" "USER COMMANDS"
.SH NAME
foo \- A frontend to the bar library
.SH SYNOPSIS
.B foo [-c config-file] file ...
.SH DESCRIPTION
.B foo
fiddles the bar library by tweaking internal
symbol tables. By default it parses all bar segments
and rearranges them  in  reverse  order  by time for the
BR foobar (1)
utility to find them.
All files are processed in the order specified
.SH OPTIONS
.IP "-c config-file"
Use the alternate system wide
.I config-file
instead of
.IR /etc/foo.conf .
This overrides any
.B FOOCONF
environment variable.
.SH FILES
.I /etc/foo.conf
.RS
The system wide configuration file. See
.BR foo (5)
for further details.
.RE
.I ~/.foorc
.RS
Per user configuration file. See
.BR foo (5)
for further details.
.SH ENVIRONMENT
.IP FOOCONF
If non-null the full pathname for an alternate system wide
.IR foo.conf .
Overridden by the
.B -c
option.
.SH DIAGNOSTICS
The following diagnostics may be issued on stderr:
 
Bad magic number.
.RS
The input file does not look like an archive file.
.RE
.SH BUGS
The command name should have been chosen more carefully
to reflect its purpose.
.SH AUTHOR
John Doe (j.doe (at) foobar.com)
.SH "SEE ALSO"
.BR bar (1),
.BR foo (5),
.BR foorbar (1)

And here is the output from man foo:

foo(1)                           USER COMMANDS                          foo(1)



NAME
       foo - A frontend to the bar library

SYNOPSIS
       foo [-c config-file] file ...

DESCRIPTION
       foo fiddles the bar library by tweaking internal symbol tables. By de-
       fault it parses all bar segments and rearranges them  in  reverse   or-
       der  by time for the BR foobar (1) utility to find them.  All files are
       processed in the order specified

OPTIONS
       -c config-file
              Use  the  alternate   system   wide   config-file  instead   of
              /etc/foo.conf.  This overrides any FOOCONF environment variable.

FILES
       /etc/foo.conf
              The  system  wide configuration file. See foo(5) for further de-
              tails.
       ~/.foorc
              Per user configuration file. See foo(5) for further details.

ENVIRONMENT
       FOOCONF
              If non-null the full  pathname  for  an  alternate  system  wide
              foo.conf.  Overridden by the -c option.

DIAGNOSTICS
       The following diagnostics may be issued on stderr:

       Bad magic number.
              The input file does not look like an archive file.

BUGS
       The  command name should have been chosen more carefully to reflect its
       purpose.

AUTHOR
       John Doe (j.doe (at) foobar.com)

SEE ALSO
       bar(1), foo(5), foorbar(1)



version 0.1                      April 1, 2001                          foo(1)

Viewing your man page

Whilst composing your man page it is good practice to review it from time to time making sure it looks right. For example, using our "foo.1" man page:

$ nroff -man foo.1 | more
$ groff -man Tascii foo.1 | less

Formatting your man page

To convert a man page to plain text use:

$ nroff -man foo.1 | col -b > foo.txt

To convert it to Postscript:

$ groff -man -Tps foo.1 > foo.ps

Converting the man page to HTML, use:

$ man2html foo.1 > foo.html