1shaman(1) shaman man page shaman(1)
2
6 shaman - the man pages viewer
7
9 shaman
10
12 About:
13 ======
14 Manual pages are part of every Unix-like system user, and this includes
15 GNU/Linux systems. Manual pages or, as they are widely known, man
16 pages, are a very convenient way to learn about a program and how it
17 works. Man pages are usually short and to the point, and they have a
18 (more or less) similar structure that makes it easy for the user to
19 navigate through them. There have been other documentation systems that
20 appeared through the years and, apart from GNU Info, most of them have
21 faded into oblivion, none of them succeeded in matching the efficiency
22 and convenience of the good ol' man pages.
23 The main downside of Unix man pages is the fact that they are text-
25 based documents that need to be read from the command line (shell, ter‐
26 minal or CLI - command line interface). For veteran users and experi‐
27 enced gurus, this is not an issue, as most of those guys live and
28 breath in the dark aether of the command line. For new and less tech-
29 savvy users, however, this is a major inconvenience. You will need to
30 be comfortable with sitting at the shell, invoking commands (man, info,
31 etc.) and then navigating through the documents using the keyboard.
32 What is Shaman?
34 ===============
35 As the Shamans of old civilizations used to summon spirits and use
36 their special powers to affect their audience, so does this software.
37 We summon the spirits of Unix creators and use the special powers
38 within the manual pages to deliver this information to the user, and
39 hence the name of the program.
40 In English, Shaman is a software package that allows the user to view,
42 search and run through the manual pages that are installed on the sys‐
43 tem. All of this is done in a Graphical User Interface (GUI) kind of
44 way, of course.
45 Package dependencies:
47 =====================
48 Manual pages are stored in a special markup language format, commonly
49 known as troff. To be able to read that markup, one needs to convert
50 troff to another format. In our case, we are relying on another pro‐
51 gram, man2html, that handles the conversion from the special markup
52 format to the HTML format. We could have written a troff parser from
53 scratch, but there are several problems with that. First, troff is a
54 very old language that have underwent several changes through the
55 years. Furthermore, many Unix-like systems extended and devleoped troff
56 for their own use, which resulted in several versions of troff. That
57 means there is a possibility that our parser might encounter a man page
58 that is written in a format it can't read. That's not good.
59 The other reason is that man2html is a long-standing effort of several
61 programmers. It has been test, re-tested, and then tested again by hun‐
62 dreds (or probably thousands) of programmers and users worldwide. That
63 means the software has been bugtested, bugfixed, and much more refined
64 than anything we would start writing right now. It's always a good
65 thing to stand on the shoulders of giants.
66 So to get Shaman to run, you need to get man2html (actually, Shaman
68 runs without man2html, but to actually view the man pages, you need
69 that software).
70 How to get man2html:
72 ====================
73 If you are using Fedora, CentOS, RedHat Enterprise Linux (RHEL), or any
74 other distro that uses dnf/yum as their package managers, you can run
75 one of those two commands (from the terminal):
76 sudo dnf install man2html
78 sudo yum install man2html
79 If you are using Debian or Ubuntu, run:
81 sudo apt-get update
83 sudo apt-get install man2html
84 Alternatively, you can download the sources from the package's website
86 at http://savannah.nongnu.org/projects/man2html/. To clone, and then
87 compile, the sources, run:
88 cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/man2html
90 co man2html
91 cd man2html
92 make && make install
93
97 Shaman gives you the ability to:
98 - View and read man pages installed on your system in a Graphical (vs
99 Text-based) environment
100 - Search for man pages about a specific topic
101 - Save man pages as HTML files (exported by man2html)
102 - Easily naviage the man pages tree on your system
103
107 -h, --help
108 Print command line help and exit
109 -v, --version
112 Display program version and exit
113
116 - Add the ability to search in man pages' titles - Autoupdate the man
117 page list when the user installs/removes software - Testing and debug‐
118 ging
119
122 info shaman
123
126 Mohammed Isam <mohammed_isam1984@yahoo.com>
1271.0 MAY 2018 shaman(1)