diff options
| -rw-r--r-- | man.cgi.7 | 78 |
1 files changed, 63 insertions, 15 deletions
@@ -12,25 +12,62 @@ The script queries and displays manual pages. It interfaces with .Xr mandocdb 8 -databases for query and with -.Xr mandoc 3 -for display. -It operates over a cache of manuals generated by +databases cached with .Xr catman 8 . .Pp To use .Nm , -first create a manual cache in +create a manual cache in .Xr catman 8 . -If your web-server is running in a jail, the cache directory must be -within the jail. -Set the environment variable -.Ev CACHE_DIR -to this directory, which defaults to +Assign this directory to the environment variable +.Ev CACHE_DIR , +defaulting to .Pa /cache/man.cgi . -If you're running in a jailed web-server, make sure the -.Pa /tmp -directory exists and is writable. +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 Er CACHE_DIR @@ -43,7 +80,7 @@ cache directory. .It Pa etc/catman.conf Built by .Xr catman 8 -and must exist under the configuration directory root. +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. @@ -55,8 +92,14 @@ 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 mandoc 3 , .Xr catman 8 , .Xr mandocdb 8 .Sh AUTHORS @@ -65,3 +108,8 @@ The 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. |