Update man.cgi.7 with new CSS files.

[mandoc.git] / man.cgi.7

diff --git a/man.cgi.7 b/man.cgi.7
index 9ede2f1112e3683945ba0c3d624c936ba25c26ac..c4a15ac2cf9d7cd0d72952e9e25b4eaeb78fb6fb 100644 (file)
--- a/man.cgi.7
+++ b/man.cgi.7
@@ -1,4 +1,4 @@
-.Dd $Mdocdate: November 24 2011 $
+.Dd $Mdocdate: December 15 2011 $

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


@@ -12,63 +12,103 @@ 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 1
-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
+databases cached with
+.Xr catman 8 .

 .Pp
 .Pp

-To run in insecure mode, drop
-.Nm
-into your web-server's CGI directory.
-The environment variable
-.Ev INSECURE
-must be set.
+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
 .Pp

-To run in secure mode, you must maintain a cache directory of
-preformatted manuals using
-.Xr manup 8 .
-If your web-server is running in a jail, the cache directory must be
-within the jail.
-Set the environment variable
+Multiple
+.Xr catman 8
+trees may be managed by
+.Nm :
+directories under

 .Ev CACHE_DIR
 .Ev CACHE_DIR

-to this directory, which defaults to
-.Pa /cache/man.cgi .
-If you're running in a jailed web-server, make sure the
-.Pa /tmp
-directory exists and is writable.
+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 INSECURE
-Run in insecure mode.
-Not recommended.
-.It Er CACHE_DIR
+.It Ev 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 in outputted HTML files.
+This must not have a trailing slash.

 .El
 .Sh FILES
 .El
 .Sh FILES

-The configuration file
-.Pa etc/man.conf
-must exist within the cache directory.
-This is built by
-.Xr manup 8 .
+.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
+Should be visible in the server document root or within
+.Ev CSS_DIR .
+Included in each page after
+.Pa man-cgi.css , 
+ostensibly for
+.Xr mandoc 1
+HTML output styling.
+.It Pa man.cgi.css
+Should be visible in the server document root or within
+.Ev CSS_DIR .
+Included in each page, ostensibly for general
+.Nm
+styling.
+.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 mandoc 1 ,
-.Xr manup 8 ,
+.Xr catman 8 ,

 .Xr mandocdb 8
 .Sh AUTHORS
 The
 .Xr mandocdb 8
 .Sh AUTHORS
 The


@@ -76,3 +116,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.