README
1This directory contains the following.
2
31. man2html
4
5This is a pure manroff -> html converter.
6No manpath search etc.
7
8Call: man2html [-l | -H host.domain:port] [filename]
9
10The contents of FILENAME (or STDIN, in case FILENAME is "-" or absent)
11are converted from man-style nroff to html, and printed on STDOUT.
12
13With "-l" URLs of the form "lynxcgi:/home/httpd/cgi-bin/..." are generated.
14With "-H host" we make URLs of the form "http://host/cgi-bin/...".
15The default is "http://localhost/cgi-bin/...".
16
172. A collection of scripts
18
19This part is not installed by "make install" of the global Makefile.
20There are security considerations: it is very unlikely that these
21scripts (still in alpha) are secure, so for the time being they
22should only be used where security is not a major concern.
23
24If you are not afraid, or are not running a httpd, do
25"make install-scripts" in this directory.
26This does three things: install man stuff, install glimpse stuff,
27and install user interface stuff.
28
292A. man stuff
30
31This first part (that can be done separately with "make install-man-scripts")
32puts various scripts under /home/httpd/cgi-bin and /home/httpd/cgi-aux
33in a subdirectory man.
34It will create a directory /var/man2html to hold the indices.
35(This directory should be writable by the cgi scripts;
36probably that means that the owner should be nobody.
37Choose a group and add all non-httpd users that should be
38able to write this directory to that group.)
39
40Structure of the collection of scripts:
41 man2html is the main script.
42 It uses man.aux when called without arguments.
43 It uses manwhatis when asked for an index of manpages+descriptions.
44 It uses mansec when asked for a compact index of manpages.
45 It uses mansearch when asked for a glimpse search.
46 In its turn mansearch uses mansearch.aux when called
47 without arguments. It uses mansearchhelp (which uses
48 mansearchhelp.aux) when asked for help.
49
502B. glimpse stuff
51The second part (that can be done separately with
52"make install-glimpse-stuff") installs .glimpse_filters
53in /var/man2html, in order to tell glimpse what decompressors to use.
54
552C. user interface stuff
56The third part (that can be done separately with "make install-hman")
57installs a user interface to these scripts in /usr/bin/hman.
58Now people can say
59 alias man=/usr/bin/hman
60and have a man that uses a html browser.
61The browser is chosen via environment variables - look at the script.
62
633. Glimpse.
64
65For the glimpse part, I quote Michael Hamilton:
66----------------------------------------------------------------------
67To use the Glimpse full text searching, you will need to install
68glimpse in /usr/bin. Redhat rpm users can get glimpse from
69
70 ftp://ftp.redhat.com/pub/contrib/i386/glimpse-4.0-6.i386.rpm
71
72The glimpse home ftp site is cs.arizona.edu. N.B. glimpse is not
73freely redistributable for commercial use, I'd be very interested in a
74more liberal alternative. Having installed glimpse, you will need to
75build a glimpse index in /var/man2html. This doesn't take too long -
76about 3 minutes on my 486DX2/66 16MB machine. As root do:
77
78 /usr/bin/glimpseindex -z -H /var/man2html /usr/man/man* /usr/X11R6/man/man* \
79 /usr/local/man/man* /opt/man/man*
80 chmod ugo+r /var/man2html/.glimpse*
81
82The -z option causes glimpse to apply any filters (for decompression etc)
83specified in /var/man2html/.glimpse_filters.
84
85This could be set up as a cron job in /etc/crontab, e.g. (the following
86must be all on one line):
87
88 21 04 * * 1 root /usr/bin/glimpseindex -z -H /var/man2html /usr/man/man*
89 /usr/X11R6/man/man* /usr/local/man/man* /opt/man/man* ;
90 chmod +r /var/man2html/.glimpse*
91--------------------------------------------------------------------------
92
93
94aeb@cwi.nl, 980119
95