Originally Published: Friday, 10 August 2001 Author: Subhasish Ghosh
Published to: develop_articles/Development Articles Page: 1/1 - [Std View]

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.

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.

The Essential Steps

There a few steps that we need to follow for creating and then installing our custom manual page in Linux. Before we dive into the steps, let's get an overview of the entire matter.

UNIX manual pages are formatted using a utility called "nroff". On Linux systems we use the GNU project's "groff". Both these are developments of an earlier "roff" or run-off command. The input to nroff or groff is plain text.

As with any other kind of programming, the easiest and best way to learn how to create a manual page in Linux is by creating one yourself.

Step 1: Boot your system into Linux, login, and at the command prompt (I am assuming you are using the CLI mode), type in: "vi catapp.1" (yes, it's a "one" at the end it's NOT an "L").

Step 2: Here's the source of a simple manual page for our application (which we have called catapp). Type it in exactly the way it's given, maintaining all the spaces and every word of it.


.TH CATAPP 1

.SH NAME catapp \- A Demonstration application that finds a naughty cat.

.SH SYNOPSIS .B catapp [\-option ...]

.SH DESCRIPTION .PP \fIcatapp\fP is a complete application that 
does nothing useful.

.PP It was written for demonstration purposes for http://www.linux.com

.SH OPTIONS .PP It doesn't have any, but let's pretend, to make 
this template complete:

.TP .BI \-option If there was an option, it would not be -option.

.SH RESOURCES .PP catapp uses almost no resources.

.SH DIAGNOSTICS The program should provide an approximate position 
where the cat ought to be found. The return value is in terms 
of time, distance and direction.

.SH SEE ALSO The only other program we know with this little 
functionality is the ubiquitous hello world application.

.SH COPYRIGHT catapp is Copyright (c) 2001-2002 Subhasish Ghosh.

This program is free software; you can redistribute it and/or modify 
it under the terms of the GNU General Public License as published 
by the Free Software Foundation; either version 2 of the License, 
or (at your option) any later version.

This program is distributed in the hope that it will be useful, 
but WITHOUT ANY WARRANTY; without even the implied warranty of 
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
GNU General Public License for more details.

You should have received a copy of the GNU General Public License 
along with this program; if not, write to the Free Software 
Foundation, Inc., 59 Temple Place, Suite 330, Boston, 
MA 02111-1307 USA.

.SH BUGS There were a few bugs, but my naughty cat ate all of them.

.SH AUTHORS Subhasish Ghosh and "geeko" the Cat. 
E-mail : subhasish_ghosh@linuxmail.org


Step 3: Okay, after typing in everything, check once more, and then save and exit. What each word means and what the macros are supposed to do will be explained later. Let's get a custom manual page running first! Now, we have the source to the manual page ready, so we can process it with Îgroffâ. The groff command commonly produces ASCII (American Standard Code for Information Interchange) text (-Tascii) or PostScript (-Tps) output. The -man option in the command line tells groff that it's a manual page that we want to create. So, type in at the command prompt (from within the same directory where the catapp.1 file resides): "groff -Tascii -man catapp.1" and press enter.

Step 4: So, we have successfully created our custom manual page in Linux. But is that all? Can we start using it already? Well, the answer is "No" because we need to install it in the proper directory for using from the command line. So, for installing our custom man page, first we need to convert it into a .gz file and then install it in /usr/share/man/man1 directory. But first, don't forget to create a backup of our text file "catapp.1". Name the backup "catapp.1.bak". We need this backup in case we need to create future manual pages, or alter the already created one (when it's converted into a .gz file and installed into the /usr/share/man/man1 directory. So type in (from within the directory that contains the file catapp.1): "cp catapp.1 catapp.1.bak" and press enter.

Step 5: The backup created, now type in: "gzip catapp.1" and press enter. This creates a file catapp.1.gz that now needs to be installed into the /usr/share/man/man1 directory for future use.

Step 6: Type in: "cp catapp.1.gz /usr/share/man/man1" and press enter. This will successfully install the custom manual page and prepare it for further use as when required. Step 7: Now for using the manual page, from the command line, just type in: "man catapp" and press enter. The first time someone asks for this manual page, the man command will automatically format and display it. The formatted manual page would provide all the information in the form as given below:


CATAPP(1)                                               CATAPP(1)


NAME catapp  -  A  Demonstration  application  that  finds  a naughty  cat.


SYNOPSIS catapp [-option ...]


DESCRIPTION catapp is a complete application that does nothing useful.


It was written for demonstration purposes for http://www.linux.com


OPTIONS It  doesn't have any, but let's pretend, to make this 
template complete:


-option If there was an option, it would not be -option.


RESOURCES catapp uses almost no resources.


DIAGNOSTICS The  program  should  provide  an  approximate  position 
where  the  cat  ought  to  be  found.  The  return  value is  in  
terms  of  time,  distance  and  direction.


SEE ALSO The only other program we know with this little  function
ality is the ubiquitous hello world application.


COPYRIGHT catapp is Copyright (c) 2001-2002 Subhasish Ghosh.

This  program  is  free  software; you can redistribute it and/or 
modify it under the terms of the GNU General Public License  as  
published  by  the  Free Software Foundation; either version 2 
of the License, or (at your  option)  any later version.

This  program  is  distributed in the hope that it will be useful, 
but WITHOUT ANY WARRANTY; without even the implied warranty  of  
MERCHANTABILITY  or FITNESS FOR A PARTICULAR PURPOSE. See the  
GNU  General  Public  License  for  more details.

You  should have received a copy of the GNU General Public License 
along with this program; if not, write to the Free Software  
Foundation,  Inc.,  59  Temple Place, Suite 330, Boston, 
MA 02111-1307 USA.


BUGS There were a few bugs, but my naughty cat ate all of them.


AUTHORS Subhasish Ghosh and "geeko" the Cat. E-mail : 
subhasish_ghosh@linuxmail.org


That's it! Please note: We started out with a text file called "catapp.1", processed it using the "groff" utility, then converted the "catapp.1" into "catapp.1.gz" and finally installed it within /usr/share/man/man1 directory. These are the only steps that one needs to follow for creating his/her own manual pages in Linux. And for future use just use the template file for creating more manual pages. One question that needs to be asked is: Hey, why did you create that compressed file using "gzip"? What's the use of this step? Well, the "man" command (atleast some versions of it) can display preformatted and compressed ASCII text versions of manual pages (as we did in this article) to speed up subsequent requests for the same page. Thus, using a .gz file increases the accessibility speed for the same manual page in the future.

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".

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!