Note that archives are being hosted at gmane.

[mandoc.git] / man.cgi.7

diff --git a/man.cgi.7 b/man.cgi.7
index 75df86163bb688653b224f5a3089712f5106203d..b02ca46881017008e67dba71e0d1dbb2560a0c08 100644 (file)
--- a/man.cgi.7
+++ b/man.cgi.7
@@ -1,4 +1,4 @@
-.Dd $Mdocdate: December 7 2011 $
+.Dd $Mdocdate: December 14 2011 $

 .Dt MAN.CGI 7
 .Os
 .Sh NAME
 .Dt MAN.CGI 7
 .Os
 .Sh NAME


@@ -12,38 +12,79 @@ The
 script queries and displays manual pages.
 It interfaces with
 .Xr mandocdb 8
 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 ,
 .Xr catman 8 .
 .Pp
 To use
 .Nm ,

-first create a manual cache in
+create a manual cache in

 .Xr catman 8 .
 .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 .
 .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
 .Sh ENVIRONMENT
 .Bl -tag -width Ds

-.It Er CACHE_DIR
+.It Ev CACHE_DIR

 The absolute path of the
 .Xr catman 8
 cache directory.
 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
 .El
 .Sh FILES
 .Bl -tag -width Ds
 .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.
 .It Pa man.css
 Must be visible in the server document root, used for styling source
 manual page output.


@@ -55,8 +96,14 @@ Must be visible in the server document root, used for general styling of
 .Nm
 search and error pages.
 .El
 .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 mandoc 3 ,

 .Xr catman 8 ,
 .Xr mandocdb 8
 .Sh AUTHORS
 .Xr catman 8 ,
 .Xr mandocdb 8
 .Sh AUTHORS


@@ -65,3 +112,8 @@ The
 utility was written by
 .An Kristaps Dzonsons ,
 .Mt kristaps@bsd.lv .
 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.