* mdocml: Update man.cgi.7 to note compatibility and running with multiple
@ 2011-12-10 23:31 kristaps
0 siblings, 0 replies; only message in thread
From: kristaps @ 2011-12-10 23:31 UTC (permalink / raw)
To: source
Log Message:
-----------
Update man.cgi.7 to note compatibility and running with multiple roots.
Modified Files:
--------------
mdocml:
man.cgi.7
Revision Data
-------------
Index: man.cgi.7
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/man.cgi.7,v
retrieving revision 1.4
retrieving revision 1.5
diff -Lman.cgi.7 -Lman.cgi.7 -u -p -r1.4 -r1.5
--- man.cgi.7
+++ man.cgi.7
@@ -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 r
.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.
--
To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2011-12-10 23:31 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-12-10 23:31 mdocml: Update man.cgi.7 to note compatibility and running with multiple kristaps
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).