diff options
Diffstat (limited to 'src/man2html/README')
| -rw-r--r-- | src/man2html/README | 280 |
1 files changed, 280 insertions, 0 deletions
diff --git a/src/man2html/README b/src/man2html/README new file mode 100644 index 00000000..8b9da9ab --- /dev/null +++ b/src/man2html/README @@ -0,0 +1,280 @@ +gnome-man2html +-------------- + +Modified version of VH-Man2html by Michael Fulbright <msf@redhat.com> + +Please do not contact the individuals below if you have problems with +gnome-man2htm, instead send me an email and I'll try to help. + +The README for the original program lies below... + + +VH-Man2html - Modified Verhoeven-man2html +----------------------------------------- +Michael Hamilton <michael@actrix.gen.nz> +http://www.actrix.gen.nz/users/michael + +vh = Richard Verhoeven's (rcb5@win.tue.nl) Man2html as modified and +packaged by Michael Hamilton. + +Featues: + - 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. + - includes section 9. + +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 rpm 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 in +/usr/doc/HTML/calderadoc/caldera.html (or somewhere like +/home/httpd/index.html if you are using RedHat's http server) + + <H3><A HREF="http:/cgi-bin/man2html"><IMG SRC="book2.gif"> + Linux Manual Pages</A></H3> + +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/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/man2html /usr/man/man* /usr/X11R6/man/man* \ + /usr/local/man/man* /opt/man/man* + chmod ugo+r /var/man2html/.glimpse* + +The -z option causes glimpse to apply any filters (for decompression etc) +specified in /var/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/man2html /usr/man/man* + /usr/X11R6/man/man* /usr/local/man/man* /opt/man/man* ; + chmod +r /var/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 for +Caldera/RedHat Linux - + + 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 Caldera/Redhat +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 rpm'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/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/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 |