Annotation of mandoc/man.cgi.8, Revision 1.1
1.1 ! schwarze 1: .\" $Id$
! 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$
! 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 AUTHORS
! 316: .An -nosplit
! 317: The
! 318: .Nm
! 319: program was written by
! 320: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
! 321: and ported to the SQLite3-based
! 322: .Xr mandoc.db 5
! 323: backend by
! 324: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to man.cgi.8 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc