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:
NAME | The name of the command or function, followed by a one-line description of what it does. |
SYNOPSIS | Usage. |
DESCRIPTION | A textual description of the functioning of the command or function. |
OPTIONS | Should include options and parameters |
RETURN VALUES | Sections (2) and (3) function calls |
ENVIRONMENT | Describe environment variables. |
FILES | Files associated with the subject |
EXAMPLES | Common usage examples and suggestions. |
DIAGNOSTICS | Normally used for section (4) device interface diagnostics. |
ERRORS | Section (2) and (3) error and signal handling |
STANDARDS | Conformance to standards if applicable. |
BUGS | List of known bugs, gotchas and caveats. |
AUTHOR | Authors contact information. |
SEE ALSO | Cross-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