Writing Man Pages in HTML
My development platform is Caldera 1.0, with a Red Hat 3.0.3 upgrade. If you don't have a Red Hat-based system, you can still successfully employ vh-man2html. If your system uses an unformatted man page source and you run an HTTP daemon, vh-man2html should still work; however, you may need to reconfigure it and rebuild the binaries to match your own setup.
Don't let having to run the HTTP daemon dissuade you. You can handle the security aspects of this process by restricting the HTTP daemon to serving your own host. I use the Apache HTTP daemon shipped with Caldera and Red Hat, so I just adjust the appropriate lines of my system's /etc/httpd/conf/access.conf file to prevent access from outside of my home network:
<Limit GET> order allow,deny allow from .pac.gen.nz deny from all </Limit>
(You can also specify that access should be restricted to a specific IP address.) Additionally, my system is configured with kernel firewalling, which provides an additional layer of protection.
The performance aspects of running an HTTP daemon are minimal. Most of the time it is idle—if other jobs need the memory the daemon is occupying, the kernel just migrates it to swap. To minimize the amount of startup activity and the total memory consumed, I reduced the number of spare daemons to one by editing /etc/httpd/conf/httpd.conf and changing the following:
MinSpareServers 1 MaxSpareServers 1 StartServers 1
This seems fine for my home network, where at most two users will be active at any one time.
vh-man2html is available in Red Hat package format in both source and i386 ELF-binary form from the following locations:
ftp://ftp.caldera.com/pub/contrib/RPMS\ /vh-man2html-1.5-1.src.rpm ftp://ftp.redhat.com/pub/contrib/SRPMS\ /vh-man2html-1.5-1.src.rpm ftp://ftp.caldera.com/pub/contrib/RPMS\ /vh-man2html-1.5-2.i386.rpm ftp://ftp.redhat.com/pub/contrib/RPMS\ /vh-man2html-1.5-2.i386.rpm
Note that ftp.redhat.com is mirrored at ftp.caldera.com.
Also, a source tar file with ELF binaries is available from:
Addtionally, Christoph Lameter, firstname.lastname@example.org, has modified vh-man2html for the Linux Debian Distribution man pages. His version is available as the man2html package in the doc directory of any Debian archive.
The rpm version will install correctly in any post-2.0.1 Red Hat-based system (including Caldera). Running the following command when logged in as root will install the binary rpm:
rpm -i vh-man2html-1.5-2.i386.rpm
After installing it you can test it by firing up your web browser and using the following URL:
http://localhost/cgi-bin/man2htmlProvided you haven't disabled your HTTP daemon, this should bring up a starter screen, where you can enter the name of a man page or follow the links to various man index pages.
You can use you browser to save this page as a bookmark. If you feel comfortable editing HTML files, you can insert it in the master document for your own system. In my case I edited my system's top-level document:
and added the following lines at an appropriate point in the document:
<H3> <A HREF="http://localhost/cgi-bin/man2html"> <IMG SRC="book2.gif"> Linux Manual Pages </A> </H3>Red Hat users would edit:
/usr/doc/HTML/index.htmland add the following to the list of available documents:
<LI><A HREF="http://localhost/cgi-bin/man2html"> Linux Manual Pages</A> <P>vh-man2html makes use of some of the files in your existing man installation. It uses the “whatis” files which are used by the Unix “man -k” command as the name-description listing. These files are built by the makewhatis command. Caldera and Red Hat systems normally build the whatis files early every morning. If these files have never been run (perhaps because you turn your machine off at night), you can build them by logging in as root user and entering:
/usr/sbin/makewhatis -wBe warned that the standard makewhatis in Caldera 1.0 takes about 30 minutes on my 486DX2-66. I have a modified version of makewhatis that does exactly the same job in only 1.5 minutes. My modified version is now available as part of man-1.4g in both rpm and tar format from:
ftp://ftp.redhat.com/redhat-3.0.3/i386\ /updates/RPMS/man-1.4g-1.i386.rpm ftp://sunsite.unc.edu/pub/Linux/system/\ Manual-pagers/man-1.4g.tar.gzSince the traditional Unix man program doesn't provide for searching the full text of the manual pages, I wanted to add this ability to vh-man2html. Enter Glimpse, a freely available program created by Udi Manber and Burra Gopal, Department of Computer Science, University of Arizona, and Sun Wu, the National Chung-Cheng University, Taiwan. Glimpse is a text file indexing and search system that achieves fast search speeds by using precomputed indices. Indexing is typically scheduled for the wee small hours of the morning, when it won't impact users.
To use the Glimpse full text searching, you must install the program Glimpse in /usr/bin. Red Hat rpm users can get Glimpse from:
The Glimpse home ftp site is:
ftp://ftp.cs.arizona.edu/Glimpse/where the latest source and prebuilt binaries (including Linux) in tar format can be found. Note that Glimpse is not freely redistributable for commercial use. I'd be very interested in hearing about any less restrictive alternatives. Having installed Glimpse, you will need to build a Glimpse index. vh-man2html expects this index to be located in /var/man2html. Building the index doesn't take very long—about three minutes on my machine. As root enter:
/usr/bin/Glimpseindex -H /var/man2html \ /usr/man/man* /usr/X11R6/man/man*\ /usr/local/man/man* /opt/man/man* chmod +r /var/man2html/.Glimpse*On Red Hat this could be set up as a cron job in /etc/crontab, e.g., (the following must be all on one line):
21 04 * * 1 root /usr/bin/Glimpseindex -H /var/man2html /usr/man/man* /usr/X11R6/man/man* /usr/local/man/man* /opt/man/man*i; chmod +r /var/man2html/.Glimpse*If you don't wish to use Glimpse, you can edit the man.html file that the package installs in /home/http/html/man.html, and remove the references to full text searches and Glimpse. This file can also be edited to include any local instructions you wish.
If you're building vh-man2html from source, you will have to manually un-tar it and change the Makefile to point to your desired installation directories before issuing a make install. You can also use the rpm2cpio utility to extract a CPIO archive from the rpm, in which case you could read the package spec file to figure out where to put things.
If you don't want to use an HTTP daemon and you know a little C, you might consider using the scripts and C program to pre-translate and pre-index all your man pages. Then they can be referred to directly without an HTTP daemon to invoke conversions on demand.
|Speed Up Your Web Site with Varnish||Jun 19, 2013|
|Non-Linux FOSS: libnotify, OS X Style||Jun 18, 2013|
|Containers—Not Virtual Machines—Are the Future Cloud||Jun 17, 2013|
|Lock-Free Multi-Producer Multi-Consumer Queue on Ring Buffer||Jun 12, 2013|
|Weechat, Irssi's Little Brother||Jun 11, 2013|
|One Tail Just Isn't Enough||Jun 07, 2013|
- Speed Up Your Web Site with Varnish
- Containers—Not Virtual Machines—Are the Future Cloud
- Linux Systems Administrator
- Lock-Free Multi-Producer Multi-Consumer Queue on Ring Buffer
- Non-Linux FOSS: libnotify, OS X Style
- Senior Perl Developer
- Technical Support Rep
- UX Designer
- RSS Feeds
- Reply to comment | Linux Journal
2 hours 3 min ago
- Yeah, user namespaces are
3 hours 20 min ago
- Cari Uang
6 hours 51 min ago
- user namespaces
9 hours 44 min ago
10 hours 10 min ago
- One advantage with VMs
12 hours 39 min ago
- about info
13 hours 12 min ago
13 hours 13 min ago
13 hours 14 min ago
13 hours 16 min ago
Free Webinar: Hadoop
How to Build an Optimal Hadoop Cluster to Store and Maintain Unlimited Amounts of Data Using Microservers
Realizing the promise of Apache® Hadoop® requires the effective deployment of compute, memory, storage and networking to achieve optimal results. With its flexibility and multitude of options, it is easy to over or under provision the server infrastructure, resulting in poor performance and high TCO. Join us for an in depth, technical discussion with industry experts from leading Hadoop and server companies who will provide insights into the key considerations for designing and deploying an optimal Hadoop cluster.
Some of key questions to be discussed are:
- What is the “typical” Hadoop cluster and what should be installed on the different machine types?
- Why should you consider the typical workload patterns when making your hardware decisions?
- Are all microservers created equal for Hadoop deployments?
- How do I plan for expansion if I require more compute, memory, storage or networking?