HowTo: Linux / UNIX Create a Manpage

How do I create a man page for my shell or python script under Linux / UNIX operating systems?

Almost all UNIX like oses comes preinstalled with man pages.

Troff and Groff Macro

troff is a document processing system developed by AT&T for the Unix operating system. The troff typesetting system includes sets of commands called macros that are run before starting to process the document. These macros include setting up page headers and footers, defining new commands, and generally influencing how the output will be formatted. Under Linux all new manual pages should be marked up using the groff an.tmac package. The groff (GNU troff) software is a typesetting package which reads plain text mixed with formatting commands and produces formatted output.

A Quick Note About Man Page Layout

All man pages follow a common layout and it is recommend that you use the same for your man pages too:

NAME
    The name of the command or function, followed by a one-line description of what it does.
SYNOPSIS
    In the case of a command, you get a formal description of how to run it and what command line options it takes.
DESCRIPTION
    A textual description of the functioning of the command or function.
EXAMPLES
    Some examples of common usage.
SEE ALSO
    A list of related commands or functions.
BUGS
    List known bugs.
AUTHOR
   Specify your contact information.
COPYRIGHT
    Specify your copyright information.

You can add a few more other sections such as EXIT STATUS, ENVIRONMENT, FILES, and HISTORY etc. The table below shows the section numbers of the manual followed by the types of pages they contain.

Man Page Sections

The manual is generally split into eight numbered sections, organized as follows under Linux or UNIX like oses:

Section	Description
1	Executable shell commands
2	System calls (functions provided by the kernel)
3	Library calls (functions within program libraries)
4	Special files (usually found in /dev)
5	File formats and conventions eg /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]

To see options and section information you can use with command man, enter the following command:

 
man man
 

Man Page Location

The system stores its man pages at /usr/share/man/ directory as described in about section. For example, the directory /usr/share/man/man1 stores man pages for user shell commands. You can view it by typing the following command:

cd  /usr/share/man/man1
ls -l
zcat ls.1.gz

Custom Man Page Location

It is recommended that you store your own man pages in /usr/local/man directory. You can set man search path in /etc/man.config file:

MANPATH /usr/man
MANPATH /usr/share/man
MANPATH /usr/local/man
MANPATH /usr/local/share/man
MANPATH /usr/X11R6/man

See manpath man page for more details about how to determine search path for manual pages:
man manpath

How Do I Create My Own Man Page?

The groff (GNU Troff) software is a typesetting package which reads plain text mixed with formatting commands and produces formatted output such as man page. It comes with various macro packages such as man and mandoc to create man pages. Create a file as follows
$ vi nuseradd

.\" Manpage for nuseradd.
.\" Contact vivek@nixcraft.net.in to correct errors or typos.
.TH man 8 "06 May 2010" "1.0" "nuseradd man page"
.SH NAME
nuseradd \- create a new LDAP user
.SH SYNOPSIS
nuseradd [USERNAME]
.SH DESCRIPTION
nuseradd is high level shell program for adding users to LDAP server.  On Debian, administrators should usually use nuseradd.debian(8) instead.
.SH OPTIONS
The nuseradd does not take any options. However, you can supply username.
.SH SEE ALSO
useradd(8), passwd(5), nuseradd.debian(8)
.SH BUGS
No known bugs.
.SH AUTHOR
Vivek Gite (vivek@nixcraft.net.in)

Save and close the file. To view your man page, enter:

man ./nuseradd

Sample outputs:

The .TH macro introduces a manual page (e.g., set man page title and section). Section headers, paragraph breaks, lists and displays etc displayed using .SH macro. See the following man page which describes all macros:
man 7 mdoc

How Do I Install My Man Page?

Simply type the following command:

cp nuseradd /usr/local/man/man8/nuseradd.1
gzip /usr/local/man/man8/nuseradd.1
man nuseradd

You can also use install command as follows (recommend for shell scripts):

install -g 0 -o 0 -m 0644 nuseradd.1 /usr/local/man/man8/
gzip /usr/local/man/man8/nuseradd.1

References:

• GNU Troff (Groff) - a GNU project.
• See man pages mdoc, groff, and install commands.

• Tweet
• 
• 

You should follow me on twitter here or grab rss feed to keep track of new changes.

Featured Articles:

• 30 Handy Bash Shell Aliases For Linux / Unix / Mac OS X
• Top 30 Nmap Command Examples For Sys/Network Admins
• 25 PHP Security Best Practices For Sys Admins
• 20 Linux System Monitoring Tools Every SysAdmin Should Know
• 20 Linux Server Hardening Security Tips
• Linux: 20 Iptables Examples For New SysAdmins
• Top 20 OpenSSH Server Best Security Practices
• Top 20 Nginx WebServer Best Security Practices
• 20 Examples: Make Sure Unix / Linux Configuration Files Are Free From Syntax Errors
• 15 Greatest Open Source Terminal Applications Of 2012
• My 10 UNIX Command Line Mistakes
• Top 10 Open Source Web-Based Project Management Software
• Top 5 Email Client For Linux, Mac OS X, and Windows Users
• The Novice Guide To Buying A Linux Laptop