man.cgi.8

   1 .\"     $Id: man.cgi.8,v 1.2 2014/07/11 21:30:52 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: July 11 2014 $
  18 .Dt MAN.CGI 8
  19 .Os
  20 .Sh NAME
  21 .Nm man.cgi
  22 .Nd CGI program to search and display manual pages
  23 .Sh DESCRIPTION
  24 The
  25 .Nm
  26 CGI program searches for manual pages on a WWW server
  27 and displays them to HTTP clients,
  28 providing functionality equivalent to the
  29 .Xr apropos 1
  30 and
  31 .Xr man 1
  32 utilities.
  33 It can use multiple manual trees in parallel.
  34 .Ss HTML search interface
  35 At the top of each generated HTML page,
  36 .Nm
  37 displays a search form containing these elements:
  38 .Bl -enum
  39 .It
  40 A
  41 .Dq Search
  42 button to send a search request from the client to the server,
  43 to be clicked after filling in the following input box(es).
  44 .It
  45 An input box for search queries, expecting an
  46 .Ar expression
  47 using the syntax described in the
  48 .Xr apropos 1
  49 manual; filling this in is required for each search.
  50 .It
  51 An input box for an optional section number.
  52 If one is provided, it has the same effect as the
  53 .Xr apropos 1
  54 .Fl s
  55 option.
  56 Otherwise, pages from all sections are shown.
  57 .It
  58 An input box for an optional architecture name.
  59 If one is provided, it has the same effect as the
  60 .Xr apropos 1
  61 .Fl S
  62 option.
  63 By default, pages for all architectures are shown.
  64 .It
  65 A dropdown menu to select a manual tree.
  66 If the configuration file
  67 .Pa /var/www/man/manpath.conf
  68 contains only one manpath, the dropdown menu is not shown.
  69 By default, the first manpath given in the file is used.
  70 .It
  71 A
  72 .Dq Reset
  73 button to undo any changes to the input boxes and the dropdown menu
  74 and reset them to the values contained in the
  75 .Ev QUERY_STRING .
  76 .El
  77 .Ss Program output
  78 The
  79 .Nm
  80 program generates five kinds of output pages:
  81 .Bl -tag -width Ds
  82 .It The index page.
  83 This is returned when calling
  84 .Nm
  85 without
  86 .Ev PATH_INFO
  87 and without a
  88 .Ev QUERY_STRING .
  89 It serves as a starting point for using the program
  90 and shows the search form only.
  91 .It A list page.
  92 Lists are returned when searches match more than one manual page.
  93 The first column shows the names and section numbers of manuals
  94 as clickable links.
  95 The second column shows the one-line descriptions of the manuals.
  96 .It A manual page.
  97 This output format is used when a search matches exactly one
  98 manual page, or when a link on a list page or an
  99 .Ic \&Xr
 100 link on another manual page is followed.
 101 .It A no-result page.
 102 This is shown when a search request returns no results -
 103 eiher because it violates the query syntax, or because
 104 the search does not match any manual pages.
 105 .It \&An error page.
 106 This cannot happen by merely clicking the
 107 .Dq Search
 108 button, but only by manually entering an invalid URI.
 109 It does not show the search form, but only an error message
 110 and a link back to the index page.
 111 .El
 112 .Ss Setup
 113 For each manual tree, create one first-level subdirectory below
 114 .Pa /var/www/man .
 115 The name of one of these directories is called a
 116 .Dq manpath
 117 in the context of
 118 .Nm .
 119 Create a single ASCII text file
 120 .Pa /var/www/man/manpath.conf
 121 containing the names of these directories, one per line.
 122 The directory given first is used as the default manpath.
 123 .Pp
 124 Inside each of these directories, use the same directory and file
 125 structure as found below
 126 .Pa /usr/share/man ,
 127 that is, second-level subdirectories
 128 .Pa /var/www/man/*/man1 , /var/www/man/*/man2
 129 etc. containing source
 130 .Xr mdoc 7
 131 and
 132 .Xr man 7
 133 manuals with file name extensions matching the section numbers,
 134 second-level subdirectories
 135 .Pa /var/www/man/*/cat1 , /var/www/man/*/cat2
 136 etc. containing preformatted manuals with the file name extension
 137 .Sq 0 ,
 138 and optional third-level subdirectories for architectures.
 139 Use
 140 .Xr makewhatis 8
 141 to create a
 142 .Xr mandoc.db 5
 143 database inside each manpath.
 144 .Pp
 145 Configure your web server to execute CGI programs located in
 146 .Pa /cgi-bin .
 147 When using
 148 .Xr nginx 8 ,
 149 the
 150 .Xr slowcgi 8
 151 proxy daemon is needed to translate FastCGI requests to plain old CGI.
 152 .Ss URI interface
 153 .Nm
 154 uniform resource identifiers are not needed for interactive use,
 155 but can be useful for deep linking.
 156 They consist of:
 157 .Bl -enum
 158 .It
 159 The
 160 .Cm http://
 161 protocol specifier.
 162 .It
 163 The host name and a following slash.
 164 .It
 165 The path to the program, normally
 166 .Pa cgi-bin/man.cgi/ .
 167 .It
 168 A page name, which can be
 169 .Cm index ,
 170 which is the default and can be omitted,
 171 .Cm search ,
 172 or
 173 .Cm show .
 174 .It
 175 For
 176 .Cm show
 177 only, a slash, the manpath, another slash,
 178 and the name of the requested file, for example
 179 .Pa /OpenBSD-current/man1/mandoc.1 .
 180 .It
 181 For
 182 .Cm search
 183 only, a query string starting with a question mark
 184 and consisting of
 185 .Ar key Ns = Ns Ar value
 186 pairs, separated by ampersands, for example
 187 .Pa ?manpath=OpenBSD-current&expr=mandoc .
 188 Supported keys are
 189 .Cm manpath ,
 190 .Cm expr ,
 191 .Cm sec ,
 192 and
 193 .Cm arch ,
 194 corresponding to
 195 .Xr apropos 1
 196 .Fl M ,
 197 .Ar expression ,
 198 .Fl s ,
 199 and
 200 .Fl S ,
 201 respectively.
 202 For backward compatibility with the traditional
 203 .Nm ,
 204 .Cm query
 205 is supported as an alias for
 206 .Cm expr
 207 and
 208 .Cm sektion
 209 as an alias for
 210 .Cm sec .
 211 .El
 212 .Sh ENVIRONMENT
 213 The web server may pass the following CGI variables to
 214 .Nm :
 215 .Bl -tag -width Ds
 216 .It Ev CSS_DIR
 217 An optional path to the directory containing the CSS files,
 218 to be specified relative to the server's document root,
 219 and to be specified without a trailing slash.
 220 When not specified, the CSS files
 221 are assumed to be in the document root.
 222 This is used in generated HTML code.
 223 .It Ev HTTP_HOST
 224 The FQDN of the (possibly virtual) host the HTTP server is running on.
 225 This is used for
 226 .Ic Location:
 227 headers in HTTP 303 responses.
 228 .It Ev MAN_DIR
 229 A path to the
 230 .Nm
 231 data directory to be used instead of
 232 .Pa /man ,
 233 relative to the web server
 234 .Xr chroot 2
 235 directory, to be specified without a trailing slash.
 236 This is prepended to the manpath when opening
 237 .Xr mandoc.db 5
 238 and manual page files.
 239 .It Ev PATH_INFO
 240 The final part of the URI path passed from the client to the server,
 241 starting after the
 242 .Ev SCRIPT_NAME
 243 and ending before the
 244 .Ev QUERY_STRING .
 245 It is used by the
 246 .Cm show
 247 page to aquire the manpath and filename it needs.
 248 .It Ev QUERY_STRING
 249 The HTTP query string passed from the client to the server.
 250 It is the final part of the URI, after the question mark.
 251 It is used by the
 252 .Cm search
 253 page to acquire the named parameters it needs.
 254 .It Ev SCRIPT_NAME
 255 The path to the
 256 .Nm
 257 binary relative to the server root, usually
 258 .Pa /cgi-bin/man.cgi .
 259 This is used for generating URIs to be embedded
 260 in generated HTML code and HTTP headers.
 261 .El
 262 .Sh FILES
 263 .Bl -tag -width Ds
 264 .It Pa /var/www
 265 Default web server
 266 .Xr chroot 2
 267 directory.
 268 All the following paths are specified relative to this directory.
 269 .It Pa /cgi-bin/man.cgi
 270 The path to the
 271 .Nm
 272 program relative to the server root.
 273 Can be overridden by
 274 .Ev SCRIPT_NAME .
 275 .It Pa /htdocs
 276 The path to the server document root relative to the server root.
 277 This is part of the web server configuration and not specific to
 278 .Nm .
 279 .It Pa /htdocs/man-cgi.css
 280 A style sheet for general
 281 .Nm
 282 styling, referenced from each generated HTML page.
 283 .It Pa /htdocs/man.css
 284 A style sheet for
 285 .Xr mandoc 1
 286 HTML styling, referenced from each generated HTML page after
 287 .Pa man-cgi.css .
 288 .It Pa /man
 289 Default
 290 .Nm
 291 data directory containing all the manual trees.
 292 Can be overridden by
 293 .Ev MAN_DIR .
 294 .It Pa /man/manpath.conf
 295 The list of available manpaths, one per line.
 296 .It Pa /man/OpenBSD-current/man1/mandoc.1
 297 An example
 298 .Xr mdoc 7
 299 source file located below the
 300 .Dq OpenBSD-current
 301 manpath.
 302 .El
 303 .Sh COMPATIBILITY
 304 The
 305 .Nm
 306 CGI program is call-compatible with queries from the traditional
 307 .Pa man.cgi
 308 script by Wolfram Schneider.
 309 However, the results may not be quite the same.
 310 .Sh SEE ALSO
 311 .Xr apropos 1 ,
 312 .Xr mandoc.db 5 ,
 313 .Xr makewhatis 8 ,
 314 .Xr slowcgi 8
 315 .Sh HISTORY
 316 A version of
 317 .Nm
 318 based on
 319 .Xr mandoc 1
 320 first appeared in mdocml-1.12.1 (March 2012).
 321 The current SQLite3-based version first appeared in
 322 .Ox 5.6 .
 323 .Sh AUTHORS
 324 .An -nosplit
 325 The
 326 .Nm
 327 program was written by
 328 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 329 and ported to the SQLite3-based
 330 .Xr mandoc.db 5
 331 backend by
 332 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .