[BACK]Return to man.cgi.8 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/man.cgi.8, Revision 1.17

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

CVSweb