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

Structure of a Man Page   Page 1 of 4  >>

Few things separate an "average" Linux user/programmer/administrator from a "good" one. When in trouble, having an exact idea where to find help is one of them. And the most important tool in finding help quickly are the manual pages that are included along with any Linux distribution. So, any time you type in a command and it doesn't work, you just type in "man command" and press enter and the manual (man for short) page associated with it is invoked and comes up on the screen.

Rather than explain how to use man pages in this article I'm going to provide a basic template that everyone can use to create their own manual pages in a flash. Everyone seems to create his/her own Linux applications nowadays, so why not provide a manual page along with it to look a bit more professional?

First of al we need an application to write a manual page about. Fortunatley I have had an awful time last week. My Linux-literate pet cat "geeko" ran away from home (supposedly with his girlfriend) for the fourth consecutive time. I was searching my Red Hat Linux distribution the other day, if I could find some man page on "Life" and "How to fix cats!", unfortunately I didn't find any.

So, I wrote an application (using C programming language) that can predict, to a certain degree of accuracy, where a cat is at any given point of time, provided a few parameters are provided while executing the application. The application is called "catapp" and we will create an man page for it here.

Structure of a Man page

If you are writing a new command or an application, you should be creating a manual page to go with it. Most manual pages have the following set pattern, which is of the form:

  1. Header
  2. Name
  3. Synopsis
  4. Description
  5. Options
  6. Resources
  7. Diagnostics
  8. See also
  9. Copyright
  10. Bugs
  11. Authors

Though most manual pages have this above-mentioned pattern it isn't compulsory for every manual page to be created in this way. You can always leave out sections that are not relevant. Please note: The above mentioned pattern for a manual page is for a "Linux" manual page. In Unix systems, the pattern is slightly different. In Unix systems, the pattern is as given below: 1. Header 2. Name 3. Synopsis 4. Description 5. Options 6. Files 7. See also 8. Bugs

We will be dealing with Linux manual pages in this article.





Structure of a Man Page   Page 1 of 4  >>