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

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.

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

	<< Page 2 of 4 >>
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.
	<< Page 2 of 4 >>