Step 1: type in: “vi myapp.1″ (yes, it’s a “one” at the end it’s NOT an “L”).
Step 2: Type it in exactly the way it’s given, maintaining all the spaces and every word of it.
.TH MYAPP 1
.SH NAME myapp \- A Demonstration application.
.SH SYNOPSIS .B myapp [\-option ...]
.SH DESCRIPTION \fImyapp\fP is a complete application that does nothing useful.
It was written for demonstration purposes for http://www.linux.com
.SH OPTIONS 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 myapp 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 myapp is Copyright (c) 2011-2012 M.Siddarth
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 XXXXX
E-mail : xxxx@xxx.org
Step 3: Okay, after typing in everything, check once more, and then save and exit. 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 myapp.1 file resides): “groff -Tascii -man myapp.1″ and press enter.
Step 4: 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 “myapp.1″. Name the backup “myapp.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 myapp.1): “cp myapp.1 myapp.1.bak” and press enter.
Step 5: The backup created, now type in: “gzip myapp.1″ and press enter. This creates a file myapp.1.gz that now needs to be installed into the /usr/share/man/man1 directory for future use.
Step 6: Type in: “cp myapp.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 myapp” and press enter. The first time someone asks for this manual page, the man command will automatically format and display it.
We started out with a text file called “myapp.1″, processed it using the “groff” utility, then converted the “myapp.1″ into “myapp.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?
Who can provide the answer?
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.
1—>>> It replaces your original file with a compressed version unlike tar which shows both compress and original file and hence memory occupied is very less.
2—->>> You can tell gzip to use different levels of compression with the flag to use compression fast and efficient.
3—>>> In case of damage to one member of a .gz file, other members can still be recovered.
i have writing the manual pages.