contrib/mdocml/man.cgi.7

   1 .Dd $Mdocdate: March 24 2012 $
   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 This must not have a trailing slash.
  78 .It Ev CSS_DIR
  79 Prepended to CSS file links in outputted HTML files.
  80 This must not have a trailing slash.
  81 .El
  82 .Sh FILES
  83 .Bl -tag -width Ds
  84 .It Pa etc/catman.conf
  85 Built by
  86 .Xr catman 8
  87 and must exist at least once under the configuration directory root.
  88 .It Pa man.css
  89 Should be visible in the server document root or within
  90 .Ev CSS_DIR .
  91 Included in each page after
  92 .Pa man-cgi.css ,
  93 ostensibly for
  94 .Xr mandoc 1
  95 HTML output styling.
  96 .It Pa man.cgi.css
  97 Should be visible in the server document root or within
  98 .Ev CSS_DIR .
  99 Included in each page, ostensibly for general
 100 .Nm
 101 styling.
 102 .El
 103 .Sh COMPATIBILITY
 104 The
 105 .Nm
 106 script is call-compatible with queries from the traditional
 107 .Pa man.cgi
 108 script by Wolfram Schneider.
 109 However, the results may not be quite the same.
 110 .Sh SEE ALSO
 111 .Xr catman 8 ,
 112 .Xr mandocdb 8
 113 .Sh AUTHORS
 114 The
 115 .Nm
 116 utility was written by
 117 .An Kristaps Dzonsons ,
 118 .Mt kristaps@bsd.lv .
 119 .Sh CAVEATS
 120 If you're running in a jailed web-server, make sure the
 121 .Pa /tmp
 122 directory exists and is writable.
 123 The databases may need this for scratch space.