From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from krisdoz.my.domain (kristaps@localhost [127.0.0.1]) by krisdoz.my.domain (8.14.5/8.14.5) with ESMTP id pBANV70x015653 for ; Sat, 10 Dec 2011 18:31:07 -0500 (EST) Received: (from kristaps@localhost) by krisdoz.my.domain (8.14.5/8.14.3/Submit) id pBANV73d015193; Sat, 10 Dec 2011 18:31:07 -0500 (EST) Date: Sat, 10 Dec 2011 18:31:07 -0500 (EST) Message-Id: <201112102331.pBANV73d015193@krisdoz.my.domain> X-Mailinglist: mdocml-source Reply-To: source@mdocml.bsd.lv MIME-Version: 1.0 From: kristaps@mdocml.bsd.lv To: source@mdocml.bsd.lv Subject: mdocml: Update man.cgi.7 to note compatibility and running with multiple X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/ Content-Type: text/plain; charset=utf-8 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