.\" man2html - UNIX Man Page to HTML translator
.TH man2html 8 "3 May 1996" "Michael Hamilton" "Linux"
man2html \- UNIX Man Page to HTML translator
\fBman2html\fP [options] [pagespec]
\fBMan2html\fP is a UNIX Man Page to HTML translator that can be
used as a CGI interface for man page access via httpd daemons.
This man2html is more formally called \fBVH-Man2html\fP - Richard
Verhoeven's Man2html modified and packaged by Michael Hamilton.
can be used to view man pages using your web browser.
locates compressed or uncompressed man pages
anywhere in the normal man hierarchy.
It translates pages in both the \fBman\fP(7) and
(BSD) macro styles.
It generates html directly from \fBtroff\fP(1) and \fBtbl\fP(1)
macro source without the need for
tbl/troff/nroff (sorry eqn isn't supported).
It generates links to other man pages, C include files, include files,
and http references.
Supporting CGI scripts allow you to browse HTML \fBwhatis\fP(1)
subject indexes and name-only indexes.
You can optionally add \fBglimpse\fP(1)
(a text indexing package) to do full text searches.
There are five ways of requesting pages:
Invoking \fBman2html\fP without parameters causes the starting page
to be presented. You can use the search-able index on the starting
page to enter requests corresponding to following requests.
.I "\fBman2html \ \fIpage_name\fP"
Invoking \fBman2html\fP with a \fIpage_name\fP" as a parameter will
cause it to search for pages that match the name. If more than one
page is located, HTML for selecting any of the pages will be generated.
If a single page is located, a redirect for full path name will
be generated - which effectively re-invokes man2html with the full
.I "\fBman2html \ \fIpage_name \ \fIsection_number\fP"
Similar to the above, but the required section is supplied to limit
.I "\fBman2html \-M \ \fP/\fIman_hierarchy_toplevel \ \fIpage_name \fP"
Similar to the above but the search is started in a particular
man page hierarchy, for example \fI/usr/local/man\fP.
.I "\fBman2html \ \fP/\fIfull_path_to_page_name\fB.\fIsection_number \fP"
The specified man page is translated. The page may optionally be
compressed with any of the compess utilities defined in \fI/etc/man.config\fP.
To use these cgi scripts from a Web browser all you have to do is
point your web browser at
You can either save this location as a bookmark or use an editor to
insert the following lines into an appropriate place in
a top level document.
<H3><A HREF="http://localhost/cgi-bin/man2html">Linux Manual Pages</A></H3>
The \fBnetscape-man\fP(1) script allows you to enter man page requests at
the command line with the output presented in Netscape. If you are
already running netscape, the script will pass the request to the
existing browser. You can can use your shell to alias the name to
something shorter if you wish.
has been tested with \fBnetscape\fP(1) version 2.0 (I recommend Helvetica
fonts) and with \fBlynx\fP(1) (lynx can't do tables). Output for a large
number of pages has been verified with \fBweblint\fP(1).
has also been tested as a server to other UNIX hosts.
For some of the indexes to work you must generate the necessary
The manwhatis CGI script uses the \fI/usr/man/whatis\fP (see \fBwhatis\fP(1)) file
to build a man page index. If this job has never been run (perhaps
because you turn your machine off at night when cron might be
scheduled to run it), you can build it by becoming the root user and
/usr/sbin/makewhatis /usr/man /usr/X11R6/man /usr/local/man
WARNING: makewhatis on my Caldera 1.0 takes about 30 minutes on my
486DX66. I have a modified version of makewhatis so that it does
exactly the same job in only 1.5 minutes. My modified version is now
available as part of man-1.4g.tar.gz:
To use the Glimpse full text searching, you will need to install
glimpse in \fI/usr/bin\fP.
The glimpse home ftp site is
Redhat rpm users can get glimpse from
N.B. glimpse is not freely redistributable for commercial use.
Having installed glimpse,
you will need to
build a glimpse index in \fI/var/cache/man2html\fP. This doesn't take too long -
about 3 minutes on my 486DX2/66 16MB machine. As root do:
/usr/bin/glimpseindex -z -H /var/cache/man2html /usr/man/man* /usr/X11R6/man/man* \
chmod ugo+r /var/cache/man2html/.glimpse*
The -z option causes glimpse to apply any filters (for decompression etc)
specified in \fI/var/cache/man2html/.glimpse_filters\fP.
This could be set up as a cron job in \fI/etc/crontab\fP, e.g. (the following
must be all on one line):
21 04 * * 1 root /usr/bin/glimpseindex -H /var/cache/man2html /usr/man/man*
/usr/X11R6/man/man* /usr/local/man/man* /opt/man/man* ;
chmod +r /var/cache/man2html/.glimpse*
To serve man pages to remote hosts, all that is required is a httpd
daemon that sets the environment variable \fBSERVER_NAME\fP correctly.
The only problem you might have with this, is if your server machine
I've modified Richard's man2html C code so that it checks all client
input parameters. It checks both for length and any characters that
Man2html will only return man or mandoc files resident in the man
hierarchy defined in \fI/etc/man.config\fP. When it returns references to
any any other kinds of files, for example, include files, they will be
"file:" references on the CLIENT host, not on the server.
The parameters to the decompression programs are checked for any
It is still possible for the contents of a man page to over-run
man2html's memory - so I guess a hacker might try to get you to
install a bogus man page in order to get man2html to do something
The scripts check their parameters for anything suspicious.
The scripts and program write suspicious requests to stderr - so they
can be found in web server log files.
Manpath and decompression configuration info from the \fBman\fP(1) config file.
Top level document loaded by man2html.
help for the search page.
The C program that translates man and mandoc macros to HTML.
Builds name-subject section indexes from the UNIX man whatis files.
Does glimpse searches.
Searches the man page to create name-only indexes.
Front end for netscape.
This directory holds a cache of indexes computed by manwhatis and mansec.
They are updated if the whatis files or man directories are updated.
The glimpse index is also expected to live here.
Used by the manwhatis script.
is used to obtain the server-name for redirects when a partial
man-page specification is translated to a complete man-page path.
.SH SEE ALSO
.BR man (1),
.BR whatis (1),
.BR apropos (1),
.BR netscape-man (1),
.BR netscape (1),
.BR lynx (1),
.BR glimpse (1),
.BR dwww (8),
This program (man2html.c) was written by Richard Verhoeven (NL:5482ZX35)
at the Eindhoven University of Technology. Email: firstname.lastname@example.org
Permission is granted to distribute, modify and use this program as long
as this comment is not removed or changed.
My modifications, packaging and scripts are copyright (c) 1996
Michael Hamilton (email@example.com). All rights reserved.
Permission is hereby granted, without written agreement and without
license or royalty fees, to use, copy, modify, and distribute this
software and its documentation for any purpose, provided that the
above copyright notice and the following two paragraphs appear in all
copies of this software.
IN NO EVENT SHALL MICHAEL HAMILTON BE LIABLE TO ANY PARTY FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF MICHAEL
HAMILTON HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
MICHAEL HAMILTON SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
ON AN "AS IS" BASIS, AND MICHAEL HAMILTON HAS NO OBLIGATION TO
PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
VH-Man2html was was written by Richard Verhoeven (NL:5482ZX35) at
the Eindhoven University of Technology (Email: firstname.lastname@example.org). The
original source is available from his web page at:
BSD mandoc support, indexing scripts, Makefile, man pages, and other
packaging were added by Michael Hamilton (email@example.com).
Maintenance and enhancement requests for this version should be directed
to Michael Hamilton (firstname.lastname@example.org).
As well as Richard, thanks are due to the following people for providing feedback
Tim Bird <email@example.com>,
Erick Branderhorst <firstname.lastname@example.org>,
Michael De La Rue <email@example.com>,
Rainer Scholz <firstname.lastname@example.org>.