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

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

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

CVSweb