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

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

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

CVSweb