www.fifi.org
    Documentation
        Manpages
        GNU Info
        Debian document tree
        Whole document tree
    Trigance web page
    Public services
    User info
    Mailing lists
    Secure server
    Multilingual usage

Manpages

Manpage of man2html

man2html

Section: Linux (8)
Updated: 3 May 1996
Index
Return to Main Contents

NAME

man2html - UNIX Man Page to HTML translator

SYNOPSIS

man2html [options] [pagespec]

DESCRIPTION

Man2html 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 VH-Man2html - Richard Verhoeven's Man2html modified and packaged by Michael Hamilton.

Man2html can be used to view man pages using your web browser. Man2html locates compressed or uncompressed man pages anywhere in the normal man hierarchy. It translates pages in both the man(7) and mandoc (BSD) macro styles. It generates html directly from troff(1) and tbl(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 whatis(1) subject indexes and name-only indexes. You can optionally add glimpse(1) (a text indexing package) to do full text searches.

There are five ways of requesting pages:

man2html: Invoking man2html 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.

man2html page_name: Invoking man2html with a page_name" 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 reference.

man2html page_name section_number: Similar to the above, but the required section is supplied to limit the search.
man2html -M /man_hierarchy_toplevel page_name: Similar to the above but the search is started in a particular man page hierarchy, for example /usr/local/man.

man2html /full_path_to_page_name.section_number: The specified man page is translated. The page may optionally be compressed with any of the compess utilities defined in /etc/manpath.config.

BROWSING

To use these cgi scripts from a Web browser all you have to do is point your web browser at

        http://localhost/cgi-bin/man2html

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 netscape-man(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.

Man2html has been tested with netscape(1) version 2.0 (I recommend Helvetica fonts) and with lynx(1) (lynx can't do tables). Output for a large number of pages has been verified with weblint(1). Man2html has also been tested as a server to other UNIX hosts.

INSTALLATION

For some of the indexes to work you must generate the necessary databases.

The manwhatis CGI script uses the /usr/man/whatis (see whatis(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 entering:

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

   ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers

To use the Glimpse full text searching, you will need to install glimpse in /usr/bin. The glimpse home ftp site is

   ftp://ftp.cs.arizona.edu/glimpse/

Redhat rpm users can get glimpse from

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

N.B. glimpse is not freely redistributable for commercial use. Having installed glimpse, you will need to build a glimpse index in /var/cache/man2html. 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*       /usr/local/man/man* /opt/man/man*
  chmod ugo+r /var/cache/man2html/.glimpse*

The -z option causes glimpse to apply any filters (for decompression etc) specified in /var/cache/man2html/.glimpse_filters. 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/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 SERVER_NAME correctly. The only problem you might have with this, is if your server machine has dual-names.

SECURITY

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 need escaping.

Man2html will only return man or mandoc files resident in the man hierarchy defined in /etc/manpath.config. 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 nasties.

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 nasty.

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.

FILES

/etc/manpath.config: Manpath and decompression configuration info from the man(1) config file.
/usr/share/doc/man2html/html/man.html: Top level document loaded by man2html.
/usr/share/doc/man2html/html/mansearch.html: Search page.
/usr/share/doc/man2html/html/mansearchhelp.html: help for the search page.
/usr/lib/cgi-bin/man2html: The C program that translates man and mandoc macros to HTML.
/usr/lib/cgi-bin/manwhatis: Builds name-subject section indexes from the UNIX man whatis files.
/usr/lib/cgi-bin/mansearch: Does glimpse searches.
/usr/lib/cgi-bin/mansec: Searches the man page to create name-only indexes.
/usr/bin/netscape-man: Front end for netscape.
/var/cache/man2html: 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.
.../man/whatis: Used by the manwhatis script.

ENVIRONMENT

SERVER_NAME: is used to obtain the server-name for redirects when a partial man-page specification is translated to a complete man-page path.

DISTRIBUTION

This program (man2html.c) was written by Richard Verhoeven (NL:5482ZX35) at the Eindhoven University of Technology. Email: rcb5@win.tue.nl

Permission is granted to distribute, modify and use this program as long as this comment is not removed or changed.

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.

AUTHORS

VH-Man2html was was written by Richard Verhoeven (NL:5482ZX35) at the Eindhoven University of Technology (Email: rcb5@win.tue.nl). The original source is available from his web page at:

http://wsinwp01.win.tue.nl:1234/maninfo.html

BSD mandoc support, indexing scripts, Makefile, man pages, and other packaging were added by Michael Hamilton (michael@actrix.gen.nz).

Maintenance and enhancement requests for this version should be directed to Michael Hamilton (michael@actrix.gen.nz).

CREDITS

As well as Richard, thanks are due to the following people for providing feedback and assistance: Tim Bird <tbird@caldera.com>, Erick Branderhorst <branderh@iaehv.nl>, Michael De La Rue <mikedlr@it.com.pl>, and Rainer Scholz <jrs@startrek.franken.de>.

This document was created by man2html, using the manual pages.
Time: 12:31:58 GMT, April 23, 2024