Originally Published: Friday, 10 August 2001 Author: Subhasish Ghosh
Published to: develop_articles/Development Articles Page: 4/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.

Man Page Sections Explained  << Page 4 of 4  

Man Page Sections Explained

Let's take a look into the different sections that we can find in the formatted manual page. As mentioned earlier, we have the following sections:
  1. Header
  2. Name
  3. Synopsis
  4. Description
  5. Options
  6. Resources
  7. Diagnostics
  8. See also
  9. Copyright
  10. Bugs
  11. Authors

Each sectionis explained below:

1. HEADER: The "HEADER" section consists of the name of the command or application that the manual page is referring to. For example, in our custom manual page, we find the name of the command, "MYAPP", followed by the section number of the man directory where this manual page has been installed.

2. NAME: The "NAME" section has a standardized format consisting of a comma-separated list of program or function names, followed by a dash, followed by a short description that defines the functionality the program (or function, or file) is supposed to provide. In the groff source it must look like .SH NAME catapp \- A Demonstration application that finds a naughty cat. The \- is important here. The backslash is needed to make the dash distinct from a hyphenation dash that may appear in either the command name or the one line description.

3. SYNOPSIS The "SYNOPSIS" section gives a short overview on available program options.

4. DESCRIPTION The "DESCRIPTION" section is supposed to explain, in detail, what this manual page refers to. Among other things, one of the most important things that must be mentioned and explained clearly is the "purpose" of the manual page and what it intends to do. For example, in our custom manual page, we have clearly mentioned that it has been written for demonstration purposes for a particular web-site named http://www.linux.com.

5. OPTIONS As its name suggests, the "OPTIONS" section gives a description of how each option affects our program behavior. Though our custom manual page really doesn't require any options, we have introduced one for demonstration purposes.

6. RESOURCES This section lists the programs or functions or files it uses. It mainly refers to configuration files, startup files, and files the program directly operates on. Catapp doesn't use any resources.

7. DIAGNOSTICS This section is mainly for providing the users with an overview of the most common error messages that may appear when executing the program and the various ways of handling them. For example, in our manual page, we have mentioned what "catapp" ought to produce as it's output, so that in case it fails to do so, the users can easily spot a mistake.

8. SEE ALSO This section consists of a list of related man pages in alphabetical order.

9. COPYRIGHT The "COPYRIGHT" section describes copyright info, including the GNU General Public License details. Please read the "COPYRIGHT" section in our custom manual page for "catapp" application for more details.

10. BUGS The "BUGS" section does what its name suggests. Predicts and states the bugs that can appear while executing the respective program or command. My application did have a lot of bugs, atleast 2 per 15 lines of code. But my Linux literate cat ate them all.

11. AUTHORS Mention the name of the "proud" authors who created this manual page. Usually are the ones who have written the accompanying application or command. In my case, it's my invisible inspiration, my Linux-literate cat "geeko" and me. "geeko" is still missing!

Another thing to be noted is the different MACROS that are in use in our source file "catapp.1". If you look carefully into the source code, the functionality of the MACROS is very easy to detect. For example,

.TH refers to "Top Header". .SH refers to "Section Headers". .B refers to the "Bold font convention". .PP refers to a paragraph break. .BI refers to "Bold alternating with italics".

These are the MACROS that have been used in our source file "catapp.1". Though many other MACROS does exist, for more details on MACROS and their corresponding functionality, please refer to the HOWTO mentioned in next section.

Conclusion

So, this is all that one needs to do for creating your own manual pages. For further in-depth reading on Manual pages, you might also take a look at the Linux Man Page mini-HowTo, written by Jens Schweikhardt as part of the Linux Documentation Project archives.

About the Author: My name is Subhasish Ghosh. I am 20 years old, currently a computer-systems engineering student in India. I am a Microsoft Certified Professional (MCP), MCSD, MCP certified on NT 4.0, recently completed Red Hat Linux Certified Engineer (RHCE) Training. I have been working with Linux for a long time, have had programmed using C, C++, VC++, VB, COM, DCOM, MFC, ATL 3.0, Perl, Python and Linux programming using GTK+. Currently busy learning the Linux Kernel Architecture in more detail and writing articles for Linux.com. E-mail: subhasish_ghosh@linuxmail.org

PLEASE NOTE: I like hearing & helping Linux users from all over the world. Anyone interested in e-mailing me can feel free to do so. However, I request computer-freaks, people who complain too much about everything and specifically egoistical Indians pretending to know everything trying to point out mistakes in my articles please NOT e-mail me. I don't have much time for that. Thank you!





Man Page Sections Explained  << Page 4 of 4