summaryrefslogtreecommitdiffstats
path: root/man.cgi.7
blob: a9a29daee65a3e611c844dbcd3728ccaa5f57df3 (plain) (blame)
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
.Dd $Mdocdate$
.Dt MAN.CGI 7
.Os
.Sh NAME
.Nm man.cgi
.Nd cgi for manpage query and display
.Sh SYNOPSIS
.Nm
.Sh DESCRIPTION
The
.Nm
script queries and displays manual pages.
It interfaces with
.Xr mandocdb 8
databases cached with
.Xr catman 8 .
.Pp
To use
.Nm ,
create a manual cache in
.Xr catman 8 .
Assign this directory to the environment variable
.Ev CACHE_DIR ,
defaulting to
.Pa /cache/man.cgi .
Copy the
.Pa man.cgi
script into your CGI directory (see
.Sx FILES
for other relevant files).
.Pp
Multiple
.Xr catman 8
trees may be managed by
.Nm :
directories under
.Ev CACHE_DIR
containing
.Pa etc/catman.conf
are identified as
.Qq manroots .
The path of a manroot under
.Ev CACHE_DIR
is converted to a name by replacing path separators with spaces.
.Pp
Thus, if
.Ev CACHE_DIR
is the default
.Pa /cache/man.cgi ,
the web-server is jailed to
.Pa /var/www ,
and cache subdirectories
.Pa ./foo/1
and
.Pa ./bar/2
contain
.Pa etc/catman.conf ,
.Nm
will assign these to manroots
.Qq foo 1
and
.Qq bar 2 ,
respectively.
These names will appear as choices when searching for manuals.
.Pp
If
.Nm
finds only one manroot, or none, then the selection box is omitted.
If no manroot is specified during search, the first manroot is used by
default.
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev CACHE_DIR
The absolute path of the
.Xr catman 8
cache directory.
This must not have a trailing slash.
.It Ev CSS_DIR
Prepended to CSS file links.
This must not have a trailing slash.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa etc/catman.conf
Built by
.Xr catman 8
and must exist at least once under the configuration directory root.
.It Pa man.css
Must be visible in the server document root, used for styling source
manual page output.
.It Pa catman.css
Must be visible in the server document root, used for styling
pre-formatted manual page output.
.It Pa man.cgi.css
Must be visible in the server document root, used for general styling of
.Nm
search and error pages.
.El
.Sh COMPATIBILITY
The
.Nm
script is call-compatible with queries from the traditional
.Pa man.cgi
script by Wolfram Schneider.
However, the results may not be quite the same.
.Sh SEE ALSO
.Xr catman 8 ,
.Xr mandocdb 8
.Sh AUTHORS
The
.Nm
utility was written by
.An Kristaps Dzonsons ,
.Mt kristaps@bsd.lv .
.Sh CAVEATS
If you're running in a jailed web-server, make sure the
.Pa /tmp
directory exists and is writable.
The databases may need this for scratch space.