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
Then type in (adjust at your will) the following structure
mysqlnas - backup the mysql databased unto the nas server
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
You need to run the script as root
Yet to be discovered
Ali Abbas ([email protected])
One saved.. run the following command
./txt2man -t Mysql2Nas -s 8 mysqlnas.txt > mysqlnas.man
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)
mv mysqlnas.man /usr/share/man/en/man8/
now type in your command line