VH-Man2html - Modified Verhoeven-man2html ----------------------------------------- Michael Hamilton http://www.actrix.gen.nz/users/michael vh = Richard Verhoeven's (rcb5@win.tue.nl) Man2html as modified and packaged by Michael Hamilton. Features: - Translate man pages to html from tbl/troff source. - Look up a page by name and section or via full path name. - Links generated html to other pages, include files, email addresses, and http refs. - Name-title index built from man whatis info. - Name only index built from inspecting the man directories. - Full text search via glimpse (glimpse obtainable separately). - Works from man and BSD mandoc source files. - Fast troff to HTML translator written in C. - Copes with compressed (gzip etc) source. New in version 1.5: - fix to mansec for compressed pages. - make now configures ALL scripts, html files, and man pages. New in version 1.4: - Uses /etc/man.config to obtain the man path. - Man2html.c now uses decompression filters specified in /etc/man.config. - Glimpse now uses decompression filters (see glimpse_filters file). (Generating indexes will be be slower for compressed hierarchies.) - Safer - more secure from memory overuns. Man2html now checks for excessively long input parameters. - All configuration can now be done by editing the Makefile and the glimpse_filters file. - By default (in version 1.4 and above) -M only allows the user to select what part of the hierarchy to search first - they cannot specify a path outside of the official hierarchy. Previously the -M option could be used to retrieve any man/mandoc source file that had "man" in it's path-name/file-name (a compile time switch can restore the previous behaviour). - Fixed more bugs. QUICK START INSTRUCTIONS ------------------------ To use these cgi scripts all you have to do is install the package and then 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.

Linux Manual Pages

For some of the indexes to work you must generate the necessary databases... Vh-man2html's manwhatis CGI-script uses the /usr/man/whatis file to build a man page index. Caldera 1.0 normally builds the /usr/man/whatis every morning at 3:21am. If this job has never been run (perhaps because you turn your machine off at night), you can build it by becoming the root user and entering: /usr/sbin/makewhatis /usr/man /usr/X11R6/man /usr/local/man WARNING: makewhatis in 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 (man-1.4g.tar.gz) and above: 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. Redhat 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 cs.arizona.edu. N.B. glimpse is not freely redistributable for commercial use, I'd be very interested in a more liberal alternative. 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 -z -H /var/cache/man2html /usr/man/man* /usr/X11R6/man/man* /usr/local/man/man* /opt/man/man* ; chmod +r /var/cache/man2html/.glimpse* If you don't want 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 might wish to include. The scripts may generate errors to the httpd error log /var/log/httpd/error_log. The man binary (used to obtain the man-path by some of the scripts) seems to always think it's talking to a tty, and tries to obtain the screen size, resulting in the following error log entries: TIOCGWINSZ failed : Bad file number To serve man pages to remote hosts, all that is required is a httpd daemon that sets the environment variable SERVER_NAME correctly. END OF QUICK START INSTRUCTIONS ------------------------------- 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 There are other man2html programs around - Richard's page has links to several of them. Richard's man2html has some useful features - Works from the troff/nroff source pages. With linux we almost always have the man source. Doesn't have to run man+tbl+eqn+nroff to generate output. Because man isn't run, no catman pages are generated. Accurate - doesn't have to guess from the man output. Does tables (eg man ascii) (but doesn't do eqn - few pages use eqn). Written in C - efficient speed/memory usage. Fast enough not to need a cache. Intelligent Makes good guesses on where to find pages. Creates links for man pages and include files. Richard's original program copes with pages formatted with the man macros. I've enhanced it by adding translations for the mandoc macros used in the BSD man pages. BSD mandoc pages in Linux include Mail, ftp, telnet, rlogin, and lpr and other printer man pages - so they're pretty important. I don't have any documentation on the mandoc macros, so I've had to guess what they intend, by looking at man source, man output and the gnroff macro definitions. I've tested it on all the BSD mandoc pages in Section 1 that I could find. It works reasonable well. There are still minor formatting glitches to do with punctuation placement. I checked the BSD mandoc with weblint, e.g. in tcsh/csh foreach i ( `egrep -l '^\.Bl' /usr/man/man1/* /usr/man/man8/*` ) /home/httpd/cgi-bin/man2html $i > tmp/`basename $i` end weblint tmp/* For broader testing: find /usr/man/man* -name '*.[0-9]' \ -printf "echo %p; /home/httpd/cgi-bin/man2html %p |weblint -x netscape -\n" \ | sh \ |& tee weblint.log If you want to sample the spectrum of mandoc translation, look at any of the pages the above grep locates, telnet, lpc, and mail are good examples. For full details of my modifications to man2html.c see the patch included in the source archive. Here's a summary of the package's components: 1) man.html - Main page or access to man2html and man indexes. 2) man2html - CGI binary that converts man pages to html. 3) manwhatis - CGI script for a name and synopsis index organised by manual section 4) mansec - CGI script for a name only index for each section. 5) mansearch - Glimpse full text searching. 6) mansearch.html - Main page or access to man2html and man indexes. 7) netscape-man - Front end that starts, or talks to, a running netscape. 8) /var/ma2html - Cache directory for indexes and glimpse indexes. All my scripts are written in awk. In detail... The manwhatis script creates section contents html files by looking for whatis files along the man path. Each whatis entry is translated to a man2html link. Manwhatis caches it's output in /var/cache/man2html/whatis-[0-9].html. The cache will be regenerated if any whatis file in the man path is updated (eg touch /usr/man/whatis). The mansec script lists the names of all manual pages for a given section by using find on the man path. It caches its output in /var/cache/man2html/manindex-[0-9].html. The cache will be regenerated if any associated man[0-9] directory in the man path is updated. The mansearch script uses glimpse to get back a list of files and matches which it links back to the actual man pages. The mansearch script is not pure awk. It's starts out as a shell script to ensure that the parameters are safely passed to awk. I think it's secure, but I'm not a cgi script expert. To build and install man2html, the scripts, and man.html from the source archive - edit the Makefile and then: make install To build binary and source rpms, placing them under /usr/src/... make rpm SECURITY -------- I've modified the man2html C code so that it checks all client input parameters for length and characters that need escaping. Man2html will only return man or mandoc files resident in the man hierarchy defined in /etc/man.config. When man2html generates references to include files they are in the form file: on the CLIENT host, not 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. CREDITS ------- See the man page man2html.8 for credits. --------------- My modifications, packaging and scripts are copyright (c) 1996 Michael Hamilton (michael@actrix.gen.nz). 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. Michael