version 1.1, 2011/11/24 12:43:34 |
version 1.9, 2011/12/14 13:36:59 |
|
|
script queries and displays manual pages. |
script queries and displays manual pages. |
It interfaces with |
It interfaces with |
.Xr mandocdb 8 |
.Xr mandocdb 8 |
databases for query and with |
databases cached with |
.Xr mandoc 1 |
.Xr catman 8 . |
for display. |
|
This script operates in two modes: secure and insecure. |
|
.Bl -tag -width Ds |
|
.It insecure |
|
Act as a web-based |
|
.Xr apropos 1 |
|
and |
|
.Xr mandoc 1 . |
|
This assumes full access to the file-system. |
|
It is not recommended for public-facing servers. |
|
.It secure |
|
Act on manual pages cached by |
|
.Xr manup 8 . |
|
A cached file tree is queried for pre-formatted manuals. |
|
.El |
|
.Pp |
.Pp |
To run in insecure mode, drop |
To use |
.Nm |
.Nm , |
into your web-server's CGI directory. |
create a manual cache in |
The environment variable |
.Xr catman 8 . |
.Ev INSECURE |
Assign this directory to the environment variable |
must be set. |
.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 |
.Pp |
To run in secure mode, you must maintain a cache directory of |
Multiple |
preformatted manuals using |
.Xr catman 8 |
.Xr manup 8 . |
trees may be managed by |
If your web-server is running in a jail, the cache directory must be |
.Nm : |
within the jail. |
directories under |
Set the environment variable |
|
.Ev CACHE_DIR |
.Ev CACHE_DIR |
to this directory, which defaults to |
containing |
.Pa /cache/man.cgi . |
.Pa etc/catman.conf |
If you're running in a jailed web-server, make sure the |
are identified as |
.Pa /tmp |
.Qq manroots . |
directory exists and is writable. |
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 |
.Sh ENVIRONMENT |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
.It Er INSECURE |
.It Ev CACHE_DIR |
Run in insecure mode. |
|
Not recommended. |
|
.It Er CACHE_DIR |
|
The absolute path of the |
The absolute path of the |
.Xr manup 8 |
.Xr catman 8 |
cache directory. |
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 |
.El |
.Sh FILES |
.Sh FILES |
The configuration file |
.Bl -tag -width Ds |
.Pa etc/man.conf |
.It Pa etc/catman.conf |
must exist within the cache directory. |
Built by |
This is built by |
.Xr catman 8 |
.Xr manup 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 |
.Sh SEE ALSO |
.Xr apropos 1 , |
.Xr catman 8 , |
.Xr mandoc 1 , |
|
.Xr manup 8 , |
|
.Xr mandocdb 8 |
.Xr mandocdb 8 |
.Sh AUTHORS |
.Sh AUTHORS |
The |
The |
|
|
utility was written by |
utility was written by |
.An Kristaps Dzonsons , |
.An Kristaps Dzonsons , |
.Mt kristaps@bsd.lv . |
.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. |