man.cgi.7

   1 .Dd $Mdocdate: December 11 2011 $
   2 .Dt MAN.CGI 7
   3 .Os
   4 .Sh NAME
   5 .Nm man.cgi
   6 .Nd cgi for manpage query and display
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Sh DESCRIPTION
  10 The
  11 .Nm
  12 script queries and displays manual pages.
  13 It interfaces with
  14 .Xr mandocdb 8
  15 databases cached with
  16 .Xr catman 8 .
  17 .Pp
  18 To use
  19 .Nm ,
  20 create a manual cache in
  21 .Xr catman 8 .
  22 Assign this directory to the environment variable
  23 .Ev CACHE_DIR ,
  24 defaulting to
  25 .Pa /cache/man.cgi .
  26 Copy the
  27 .Pa man.cgi
  28 script into your CGI directory (see
  29 .Sx FILES
  30 for other relevant files).
  31 .Pp
  32 Multiple
  33 .Xr catman 8
  34 trees may be managed by
  35 .Nm :
  36 directories under
  37 .Ev CACHE_DIR
  38 containing
  39 .Pa etc/catman.conf
  40 are identified as
  41 .Qq manroots .
  42 The path of a manroot under
  43 .Ev CACHE_DIR
  44 is converted to a name by replacing path separators with spaces.
  45 .Pp
  46 Thus, if
  47 .Ev CACHE_DIR
  48 is the default
  49 .Pa /cache/man.cgi ,
  50 the web-server is jailed to
  51 .Pa /var/www ,
  52 and cache subdirectories
  53 .Pa ./foo/1
  54 and
  55 .Pa ./bar/2
  56 contain
  57 .Pa etc/catman.conf ,
  58 .Nm
  59 will assign these to manroots
  60 .Qq foo 1
  61 and
  62 .Qq bar 2 ,
  63 respectively.
  64 These names will appear as choices when searching for manuals.
  65 .Pp
  66 If
  67 .Nm
  68 finds only one manroot, or none, then the selection box is omitted.
  69 If no manroot is specified during search, the first manroot is used by
  70 default.
  71 .Sh ENVIRONMENT
  72 .Bl -tag -width Ds
  73 .It Ev CACHE_DIR
  74 The absolute path of the
  75 .Xr catman 8
  76 cache directory.
  77 .It Ev CSS_DIR
  78 Prepended to CSS file links.
  79 .El
  80 .Sh FILES
  81 .Bl -tag -width Ds
  82 .It Pa etc/catman.conf
  83 Built by
  84 .Xr catman 8
  85 and must exist at least once under the configuration directory root.
  86 .It Pa man.css
  87 Must be visible in the server document root, used for styling source
  88 manual page output.
  89 .It Pa catman.css
  90 Must be visible in the server document root, used for styling
  91 pre-formatted manual page output.
  92 .It Pa man.cgi.css
  93 Must be visible in the server document root, used for general styling of
  94 .Nm
  95 search and error pages.
  96 .El
  97 .Sh COMPATIBILITY
  98 The
  99 .Nm
 100 script is call-compatible with queries from the traditional
 101 .Pa man.cgi
 102 script by Wolfram Schneider.
 103 However, the results may not be quite the same.
 104 .Sh SEE ALSO
 105 .Xr catman 8 ,
 106 .Xr mandocdb 8
 107 .Sh AUTHORS
 108 The
 109 .Nm
 110 utility was written by
 111 .An Kristaps Dzonsons ,
 112 .Mt kristaps@bsd.lv .
 113 .Sh CAVEATS
 114 If you're running in a jailed web-server, make sure the
 115 .Pa /tmp
 116 directory exists and is writable.
 117 The databases may need this for scratch space.