|[Home] [Credit Search] [Category Browser] [Staff Roll Call]||The LINUX.COM Article Archive|
|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.
|the Essential Steps||<< 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.
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:
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.
|the Essential Steps||<< Page 2 of 4 >>|