Writing Man Pages in HTML

HTML is a cool way to look at the Linux man pages. Here's how to do it.

Obtaining and Installing vh-man2html

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:

Addtionally, Christoph Lameter, clameter@waterf.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/man2html

Provided 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:

/usr/doc/HTML/calderadoc/caldera.html

and added the following lines at an appropriate point in the
document:

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 -w

Be 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:

Since 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:

ftp://ftp.redhat.com/pub/non-free\
/Glimpse-3.0-1.i386.rpm

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:

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.