December 12, 2008

Create your own manpage

Those who know me, know that I usually tend to document every little hack, server modification, kernel update and events that I happened to correct, install, modify, hack or fix!

I mainly do this as to keep on being productive but as well as keeping other admins updated on the modification which happened on the server.

Having said that! Most of us find ourselves often in front of a console terminal and sometimes in need of a memory refresh… wether it is us who can’t remember how we fixed a specific problem or another system administration who wonders “why is this perl script here and what does it do”.

Now… one could either set a homepage, create a documentation (wiki) and say “check this url for further info”. Considering that this is a cool alternative, it gets trickier when you are sitting in the server room with only the holy black console. Your server could have no connectivity, thus paralyzing you to fetch any remote documentation.

Many reasons, why manpages are cool tricks and since we are cool people! why not.

Now, let’s imagine I have a bash/perl script called “MysqlNas”.. this script does one thing and this thing is to backup through a cron, the server’s mysql table unto a NAS.

Now let’s create a manpage for our script, so that anyone who types “man mysqlnas” will get a rich set of infos / warnings / update version OR even server hacks we had to do, to make the script work (well let’s imagine :) ).

We are going to use a free utiliy called txt2man… the utility can be downloaded from the FSF website at http://directory.fsf.org/project/txt2man/

txt2man is a shell script, so you will call it as in ./txt2man

Create a txt file which will contain your program infos

[sourcecode=“bash”]

vi mysqlnas.txt

[/sourcecode]

Then type in (adjust at your will) the following structure

[sourcecode=“bash”]

NAME mysqlnas - backup the mysql databased unto the nas server

SYNOPSIS /usr/bin/mysqlnas.pl database_name

DESCRIPTION MysqlNas is a cool perl script which will recursively backup every database in /var/lib/mysql

A command argument could be parsed to the script to backup a single database… no ARG will result in the backup of all databases

ENVIRONMENT

You need to run the script as root

BUGS

Yet to be discovered

AUTHOR

Ali Abbas ([email protected])

[/sourcecode]

One saved.. run the following command

[sourcecode=“bash”]

./txt2man -t Mysql2Nas -s 8 mysqlnas.txt > mysqlnas.man

[/sourcecode]

And voila we have created our manapage :) … Now we need to move the mysqlnas.man page into the /usr/share/man/(language)/manX/ for our man command to locate it.

** (language) : correspond to your system’s language! in our case, it would be “en” ** (X): correspond to the manpage section… we have set “-s 8”, meaning we are create our manapage in section 8 of the manage sections (for more info, refer to Wikipedia Manapage Sections)

so

[sourcecode=“bash”]

mv mysqlnas.man /usr/share/man/en/man8/

[/sourcecode]

now type in your command line

[sourcecode=“bash”]

man mysqlnas

[/sourcecode]

enjoy :)