contrib/mdocml/man.cgi.8

   1 .\"     $Id: man.cgi.8,v 1.13 2015/11/05 20:55:41 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: November 5 2015 $
  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 An input box for search queries, expecting
  41 either a name of a manual page or an
  42 .Ar expression
  43 using the syntax described in the
  44 .Xr apropos 1
  45 manual; filling this in is required for each search.
  46 .Pp
  47 The expression is broken into words at whitespace.
  48 Whitespace characters and backslashes can be escaped
  49 by prepending a backslash.
  50 The effect of prepending a backslash to another character is undefined;
  51 in the current implementation, it has no effect.
  52 .It
  53 A
  54 .Dq Submit
  55 button to send a search request from the client to the server.
  56 .It
  57 A
  58 .Dq Reset
  59 button to undo any changes to the input boxes and the dropdown menus
  60 and reset them to the values contained in the
  61 .Ev QUERY_STRING .
  62 .It
  63 Radio buttons to select pages either by name like in
  64 .Xr man 1
  65 or using
  66 .Xr apropos 1
  67 queries.
  68 .It
  69 A dropdown menu to optionally select a manual section.
  70 If one is provided, it has the same effect as the
  71 .Xr man 1
  72 and
  73 .Xr apropos 1
  74 .Fl s
  75 option.
  76 Otherwise, pages from all sections are shown.
  77 .It
  78 A dropdown menu to optionally select an architecture.
  79 If one is provided, it has the same effect as the
  80 .Xr man 1
  81 and
  82 .Xr apropos 1
  83 .Fl S
  84 option.
  85 By default, pages for all architectures are shown.
  86 .It
  87 A dropdown menu to select a manual tree.
  88 If the configuration file
  89 .Pa /var/www/man/manpath.conf
  90 contains only one manpath, the dropdown menu is not shown.
  91 By default, the first manpath given in the file is used.
  92 .El
  93 .Ss Program output
  94 The
  95 .Nm
  96 program generates five kinds of output pages:
  97 .Bl -tag -width Ds
  98 .It The index page.
  99 This is returned when calling
 100 .Nm
 101 without
 102 .Ev PATH_INFO
 103 and without a
 104 .Ev QUERY_STRING .
 105 It serves as a starting point for using the program
 106 and shows the search form only.
 107 .It A list page.
 108 Lists are returned when searches match more than one manual page.
 109 The first column shows the names and section numbers of manuals
 110 as clickable links.
 111 The second column shows the one-line descriptions of the manuals.
 112 .It A manual page.
 113 This output format is used when a search matches exactly one
 114 manual page, or when a link on a list page or an
 115 .Ic \&Xr
 116 link on another manual page is followed.
 117 .It A no-result page.
 118 This is shown when a search request returns no results -
 119 eiher because it violates the query syntax, or because
 120 the search does not match any manual pages.
 121 .It \&An error page.
 122 This cannot happen by merely clicking the
 123 .Dq Search
 124 button, but only by manually entering an invalid URI.
 125 It does not show the search form, but only an error message
 126 and a link back to the index page.
 127 .El
 128 .Ss Setup
 129 For each manual tree, create one first-level subdirectory below
 130 .Pa /var/www/man .
 131 The name of one of these directories is called a
 132 .Dq manpath
 133 in the context of
 134 .Nm .
 135 Create a single ASCII text file
 136 .Pa /var/www/man/manpath.conf
 137 containing the names of these directories, one per line.
 138 The directory given first is used as the default manpath.
 139 .Pp
 140 Inside each of these directories, use the same directory and file
 141 structure as found below
 142 .Pa /usr/share/man ,
 143 that is, second-level subdirectories
 144 .Pa /var/www/man/*/man1 , /var/www/man/*/man2
 145 etc. containing source
 146 .Xr mdoc 7
 147 and
 148 .Xr man 7
 149 manuals with file name extensions matching the section numbers,
 150 second-level subdirectories
 151 .Pa /var/www/man/*/cat1 , /var/www/man/*/cat2
 152 etc. containing preformatted manuals with the file name extension
 153 .Sq 0 ,
 154 and optional third-level subdirectories for architectures.
 155 Use
 156 .Xr makewhatis 8
 157 to create a
 158 .Xr mandoc.db 5
 159 database inside each manpath.
 160 .Pp
 161 Configure your web server to execute CGI programs located in
 162 .Pa /cgi-bin .
 163 When using
 164 .Ox
 165 .Xr httpd 8
 166 or
 167 .Xr nginx 8 ,
 168 the
 169 .Xr slowcgi 8
 170 proxy daemon is needed to translate FastCGI requests to plain old CGI.
 171 .Pp
 172 To compile
 173 .Nm ,
 174 first copy
 175 .Pa cgi.h.example
 176 to
 177 .Pa cgi.h
 178 and edit it according to your needs.
 179 It contains the following compile-time definitions:
 180 .Bl -tag -width Ds
 181 .It Ev COMPAT_OLDURI
 182 Only useful for running on www.openbsd.org to deal with old URIs containing
 183 .Qq "manpath=OpenBSD "
 184 where the blank character has to be translated to a hyphen.
 185 When compiling for other sites, this definition can be deleted.
 186 .It Ev CSS_DIR
 187 An optional path to the directory containing the CSS files,
 188 to be specified relative to the server's document root,
 189 and to be specified without a trailing slash.
 190 When not specified, the CSS files
 191 are assumed to be in the document root.
 192 This is used in generated HTML code.
 193 .It Ev CUSTOMIZE_TITLE
 194 An ASCII string to be used for the HTML <TITLE> element.
 195 .It Ev HTTP_HOST
 196 The FQDN of the (possibly virtual) host the HTTP server is running on.
 197 This is used for
 198 .Ic Location:
 199 headers in HTTP 303 responses.
 200 .It Ev MAN_DIR
 201 A path to the
 202 .Nm
 203 data directory to be used instead of
 204 .Pa /var/www/man ,
 205 relative to the web server
 206 .Xr chroot 2
 207 directory, to be specified without a trailing slash.
 208 This is prepended to the manpath when opening
 209 .Xr mandoc.db 5
 210 and manual page files.
 211 .El
 212 .Pp
 213 After editing
 214 .Pa cgi.h ,
 215 run
 216 .Pp
 217 .Dl make man.cgi
 218 .Pp
 219 and copy the files to the proper locations.
 220 Reading the
 221 .Cm installcgi
 222 target in the
 223 .Pa Makefile
 224 can help with that, but do not run it without carefully checking it
 225 because the directory layouts of web servers vary greatly.
 226 .Ss URI interface
 227 .Nm
 228 uniform resource identifiers are not needed for interactive use,
 229 but can be useful for deep linking.
 230 They consist of:
 231 .Bl -enum
 232 .It
 233 The
 234 .Cm http://
 235 protocol specifier.
 236 .It
 237 The host name and a following slash.
 238 .It
 239 The path to the program, normally
 240 .Pa cgi-bin/man.cgi/ .
 241 .It
 242 To show a single page, a slash, the manpath, another slash,
 243 and the name of the requested file, for example
 244 .Pa /OpenBSD-current/man1/mandoc.1 .
 245 .It
 246 For searches, a query string starting with a question mark
 247 and consisting of
 248 .Ar key Ns = Ns Ar value
 249 pairs, separated by ampersands, for example
 250 .Pa ?manpath=OpenBSD-current&query=mandoc .
 251 Supported keys are
 252 .Cm manpath ,
 253 .Cm query ,
 254 .Cm sec ,
 255 .Cm arch ,
 256 corresponding to
 257 .Xr apropos 1
 258 .Fl M ,
 259 .Ar expression ,
 260 .Fl s ,
 261 .Fl S ,
 262 respectively, and
 263 .Cm apropos ,
 264 which is a boolean parameter to select or deselect the
 265 .Xr apropos 1
 266 query mode.
 267 For backward compatibility with the traditional
 268 .Nm ,
 269 .Cm sektion
 270 is supported as an alias for
 271 .Cm sec .
 272 .El
 273 .Ss Restricted character set
 274 For security reasons, in particular to prevent cross site scripting
 275 attacks, some strings used by
 276 .Nm
 277 can only contain the following characters:
 278 .Pp
 279 .Bl -dash -compact -offset indent
 280 .It
 281 lower case and upper case ASCII letters
 282 .It
 283 the ten decimal digits
 284 .It
 285 the dash
 286 .Pq Sq -
 287 .It
 288 the dot
 289 .Pq Sq \&.
 290 .It
 291 the slash
 292 .Pq Sq /
 293 .It
 294 the underscore
 295 .Pq Sq _
 296 .El
 297 .Pp
 298 In particular, this applies to the
 299 .Ev SCRIPT_NAME ,
 300 to all manpaths, and to all architecture names.
 301 .Sh ENVIRONMENT
 302 The web server may pass the following CGI variables to
 303 .Nm :
 304 .Bl -tag -width Ds
 305 .It Ev PATH_INFO
 306 The final part of the URI path passed from the client to the server,
 307 starting after the
 308 .Ev SCRIPT_NAME
 309 and ending before the
 310 .Ev QUERY_STRING .
 311 It is used by the
 312 .Cm show
 313 page to acquire the manpath and filename it needs.
 314 .It Ev QUERY_STRING
 315 The HTTP query string passed from the client to the server.
 316 It is the final part of the URI, after the question mark.
 317 It is used by the
 318 .Cm search
 319 page to acquire the named parameters it needs.
 320 .It Ev SCRIPT_NAME
 321 The path to the
 322 .Nm
 323 binary relative to the server root, usually
 324 .Pa /cgi-bin/man.cgi .
 325 This is used for generating URIs to be embedded
 326 in generated HTML code and HTTP headers.
 327 If this contains any character not contained in the
 328 .Sx Restricted character set ,
 329 .Nm
 330 reports an internal server error and exits without doing anything.
 331 .El
 332 .Sh FILES
 333 .Bl -tag -width Ds
 334 .It Pa /var/www
 335 Default web server
 336 .Xr chroot 2
 337 directory.
 338 All the following paths are specified relative to this directory.
 339 .It Pa /cgi-bin/man.cgi
 340 The path to the
 341 .Nm
 342 program relative to the server root.
 343 Can be overridden by
 344 .Ev SCRIPT_NAME .
 345 .It Pa /htdocs
 346 The path to the server document root relative to the server root.
 347 This is part of the web server configuration and not specific to
 348 .Nm .
 349 .It Pa /htdocs/mandoc.css
 350 A style sheet for
 351 .Xr mandoc 1
 352 HTML styling, referenced from each generated HTML page.
 353 .It Pa /man
 354 Default
 355 .Nm
 356 data directory containing all the manual trees.
 357 Can be overridden by
 358 .Ev MAN_DIR .
 359 .It Pa /man/mandoc/man1/apropos.1 , /man/mandoc/man8/man.cgi.8
 360 Manual pages documenting
 361 .Nm
 362 itself, linked from the index page.
 363 .It Pa /man/manpath.conf
 364 The list of available manpaths, one per line.
 365 If any of the lines in this file contains a slash
 366 .Pq Sq /
 367 or any character not contained in the
 368 .Sx Restricted character set ,
 369 .Nm
 370 reports an internal server error and exits without doing anything.
 371 .It Pa /man/header.html
 372 An optional file containing static HTML code to be inserted right
 373 after opening the <BODY> element.
 374 .It Pa /man/footer.html
 375 An optional file containing static HTML code to be inserted right
 376 before closing the <BODY> element.
 377 .It Pa /man/OpenBSD-current/man1/mandoc.1
 378 An example
 379 .Xr mdoc 7
 380 source file located below the
 381 .Dq OpenBSD-current
 382 manpath.
 383 .El
 384 .Sh COMPATIBILITY
 385 The
 386 .Nm
 387 CGI program is call-compatible with queries from the traditional
 388 .Pa man.cgi
 389 script by Wolfram Schneider.
 390 However, the output may not be quite the same.
 391 .Sh SEE ALSO
 392 .Xr apropos 1 ,
 393 .Xr mandoc.db 5 ,
 394 .Xr makewhatis 8 ,
 395 .Xr slowcgi 8
 396 .Sh HISTORY
 397 A version of
 398 .Nm
 399 based on
 400 .Xr mandoc 1
 401 first appeared in mdocml-1.12.1 (March 2012).
 402 The current SQLite3-based version first appeared in
 403 .Ox 5.6 .
 404 .Sh AUTHORS
 405 .An -nosplit
 406 The
 407 .Nm
 408 program was written by
 409 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 410 and ported to the SQLite3-based
 411 .Xr mandoc.db 5
 412 backend by
 413 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .