shaman - Man Page

shaman

About:
======
Manual pages are part of every Unix-like system user, and this includes GNU/Linux systems. Manual pages or, as they are widely known, man pages, are a very convenient way to learn about a program and how it works. Man pages are usually short and to the point, and they have a (more or less) similar structure that makes it easy for the user to navigate through them. There have been other documentation systems that appeared through the years and, apart from GNU Info, most of them have faded into oblivion, none of them succeeded in matching the efficiency and convenience of the good ol' man pages.

The main downside of Unix man pages is the fact that they are text-based documents that need to be read from the command line (shell, terminal or CLI - command line interface). For veteran users and experienced gurus, this is not an issue, as most of those guys live and breath in the dark aether of the command line. For new and less tech-savvy users, however, this is a major inconvenience. You will need to be comfortable with sitting at the shell, invoking commands (man, info, etc.) and then navigating through the documents using the keyboard.

What is Shaman?
===============
As the Shamans of old civilizations used to summon spirits and use their special powers to affect their audience, so does this software. We summon the spirits of Unix creators and use the special powers within the manual pages to deliver this information to the user, and hence the name of the program.

In English, Shaman is a software package that allows the user to view, search and run through the manual pages that are installed on the system. All of this is done in a Graphical User Interface (GUI) kind of way, of course.

Package dependencies:
=====================
Manual pages are stored in a special markup language format, commonly known as troff. To be able to read that markup, one needs to convert troff to another format. In our case, we are relying on another program, man2html, that handles the conversion from the special markup format to the HTML format. We could have written a troff parser from scratch, but there are several problems with that. First, troff is a very old language that have underwent several changes through the years. Furthermore, many Unix-like systems extended and devleoped troff for their own use, which resulted in several versions of troff. That means there is a possibility that our parser might encounter a man page that is written in a format it can't read. That's not good.

The other reason is that man2html is a long-standing effort of several programmers. It has been test, re-tested, and then tested again by hundreds (or probably thousands) of programmers and users worldwide. That means the software has been bugtested, bugfixed, and much more refined than anything we would start writing right now. It's always a good thing to stand on the shoulders of giants.

So to get Shaman to run, you need to get man2html (actually, Shaman runs without man2html, but to actually view the man pages, you need that software).

How to get man2html:
====================
If you are using Fedora, CentOS, RedHat Enterprise Linux (RHEL), or any other distro that uses dnf/yum as their package managers, you can run one of those two commands (from the terminal):

sudo dnf install man2html
sudo yum install man2html

If you are using Debian or Ubuntu, run:

sudo apt-get update
sudo apt-get install man2html

Alternatively, you can download the sources from the package's website at http://savannah.nongnu.org/projects/man2html/. To clone, and then compile, the sources, run:

cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/man2html co man2html
cd man2html
make && make install

Shaman gives you the ability to:
- View and read man pages installed on your system in a Graphical (vs Text-based) environment
- Search for man pages about a specific topic
- Save man pages as HTML files (exported by man2html)
- Easily naviage the man pages tree on your system

-h,  --help

Print command line help and exit

-v,  --version

Display program version and exit

- Add the ability to search in man pages' titles - Autoupdate the man page list when the user installs/removes software - Testing and debugging

info shaman

Mohammed Isam <mohammed_isam1984@yahoo.com>