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

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

1.2     ! schwarze    1: .\"     $Id: man.cgi.8,v 1.1 2014/07/10 00:31:10 schwarze Exp $
1.1       schwarze    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: .\"
1.2     ! schwarze   17: .Dd $Mdocdate: July 10 2014 $
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
                     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
1.2     ! schwarze  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 .
1.1       schwarze  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 .

CVSweb