File: man2html.8

package info (click to toggle)
man2html 1.5-23.1
  • links: PTS
  • area: main
  • in suites: potato
  • size: 344 kB
  • ctags: 218
  • sloc: ansic: 3,889; awk: 241; sh: 224; makefile: 124
file content (259 lines) | stat: -rw-r--r-- 9,798 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
.\" man2html - UNIX Man Page to HTML translator
.TH man2html 8 "3 May 1996" "Michael Hamilton" "Linux"
.SH NAME
man2html \- UNIX Man Page to HTML translator
.SH SYNOPSIS
\fBman2html\fP [options] [pagespec] 
.SH DESCRIPTION
\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.

.B Man2html
can be used to view man pages using your web browser.
.B Man2html 
locates compressed or uncompressed man pages
anywhere in the normal man hierarchy.
It translates pages in both the \fBman\fP(7) and 
.I mandoc 
(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.
.PP
There are five ways of requesting pages:

.TP
.I "\fBman2html"
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.
.PP
.TP
.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
reference.
.PP
.TP
.I "\fBman2html \ \fIpage_name \ \fIsection_number\fP"
Similar to the above, but the required section is supplied to limit
the search.
.TP
.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.
.PP
.TP
.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.
.SH BROWSING 
To use these cgi scripts from a Web browser all you have to do is
point your web browser at
.nf
        http://localhost/cgi-bin/man2html 
.fi
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.
.nf
   <H3><A HREF="http://localhost/cgi-bin/man2html">Linux Manual Pages</A></H3>
.fi
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.

.B Man2html 
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).
.B Man2html 
has also been tested as a server to other UNIX hosts.
.SH INSTALLATION
For some of the indexes to work you must generate the necessary
databases.

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
entering:
.nf
   /usr/sbin/makewhatis /usr/man /usr/X11R6/man /usr/local/man
.fi
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:
.nf
   ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers
.fi
To use the Glimpse full text searching, you will need to install
glimpse in \fI/usr/bin\fP.  
The glimpse home ftp site is 
.nf
   ftp://ftp.cs.arizona.edu/glimpse/
.fi
Redhat rpm users can get glimpse from 
.nf
   ftp://ftp.redhat.com/pub/non-free/glimpse-3.0-1.i386.rpm
.fi
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:
.nf
  /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*
.fi
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):
.nf
   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*
.fi
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
has dual-names.
.SH 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 \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
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.
.SH FILES
.TP
.I /etc/man.config
Manpath and decompression configuration info from the \fBman\fP(1) config file.
.TP
.I /home/httpd/html/man.html
Top level document loaded by man2html.
.TP
.I /home/httpd/html/mansearch.html
Search page.
.TP
.I /home/httpd/html/mansearchhelp.html
help for the search page.
.TP
.I /home/httpd/cgi-bin/man2html
The C program that translates man and mandoc macros to HTML.
.TP
.I /home/httpd/cgi-bin/manwhatis
Builds name-subject section indexes from the UNIX man whatis files.
.TP
.I /home/httpd/cgi-bin/mansearch
Does glimpse searches.
.TP
.I /home/httpd/cgi-bin/mansec
Searches the man page to create name-only indexes.
.TP
.I /usr/bin/netscape-man       
Front end for netscape.
.TP
.I /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.
.TP
.I \.\.\./man/whatis
Used by the manwhatis script.
.SH ENVIRONMENT
.TP 
.B 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. 
.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),
.B http://www.actrix.gen.nz/users/michael/giveaways.html

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

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.
.SH 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).
.SH 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>.