Linux.com Article DB: Creating a Linux Manual (man) Page

Organizing Your Man Page

When we consider manual pages in Linux, if one goes to the /usr/share/man directory, he/she would find that there exists a few directories. We consider the directories named man1 to man9, which contain man pages in Linux. What are these directories and why are they named man1 to man9? Each directory consist of manual pages, but the directory section number, that is the numerical after the word "man" decides what the directory contains, and who can access the man pages inside it and can invoke it accordingly. In other words the "section numbers" define the accessibility of manual pages in Linux. The most common sections under Linux, and their human readable names, are:

Section	The human readable name
1	User commands that may be started by everyone.
2	System calls, that is, functions provided by the kernel.
3	Subroutines, that is, library functions.
4	Devices, that is, special files in the /dev directory.
5	File format descriptions, e.g. /etc/passwd.
6	Games, self-explanatory.
7	Miscellaneous, e.g. macro packages, conventions.
8	System administration tools that only root can execute.
9	Another (Linux specific) place for kernel routine documentation.

Thus, when we created our custom manual page for our application catapp, and when installing it in the proper location we muct make sure it installed in the directory man1. The reason being we want the manual page for catapp to be accessible by all.

Another point to be noted is: Why did we name the file containing the source code for our manual page "catapp.1" ? What does this ".1" indicate? The answer to this question again lies in the section just discussed above. The name of the man page's source file (the input to the formatting system) is the name of the command, function or file name, followed by a dot, followed by the section character. Thus our source file reads "catapp.1" where catapp is the name of the command or the application it is referring to, a ".", and then the section number of the man directory where it ought to be installed. Hence, we have the source file named: "catapp.1".

Originally Published: Friday, 10 August 2001	Author: Subhasish Ghosh
Published to: develop_articles/Development Articles	Page: 3/4 - [Printable]
Creating a Linux Manual (man) Page Most of us know just how useful a man page is and many of us actually read them. But it's not always easy to know how to create a good man page for Linux. In this article Linux.com editorial correspondent Subhasish Ghosh takes on the task and fills us in on the results.