=================================================================== RCS file: /cvs/mandoc/man.cgi.8,v retrieving revision 1.1 retrieving revision 1.8 diff -u -p -r1.1 -r1.8 --- mandoc/man.cgi.8 2014/07/10 00:31:10 1.1 +++ mandoc/man.cgi.8 2014/07/21 15:45:17 1.8 @@ -1,4 +1,4 @@ -.\" $Id: man.cgi.8,v 1.1 2014/07/10 00:31:10 schwarze Exp $ +.\" $Id: man.cgi.8,v 1.8 2014/07/21 15:45:17 schwarze Exp $ .\" .\" Copyright (c) 2014 Ingo Schwarze .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: July 10 2014 $ +.Dd $Mdocdate: July 21 2014 $ .Dt MAN.CGI 8 .Os .Sh NAME @@ -37,26 +37,42 @@ At the top of each generated HTML page, displays a search form containing these elements: .Bl -enum .It -A -.Dq Search -button to send a search request from the client to the server, -to be clicked after filling in the following input box(es). -.It -An input box for search queries, expecting an +An input box for search queries, expecting +either a name of a manual page or an .Ar expression using the syntax described in the .Xr apropos 1 manual; filling this in is required for each search. .It -An input box for an optional section number. +A +.Dq Submit +button to send a search request from the client to the server. +.It +A +.Dq Reset +button to undo any changes to the input boxes and the dropdown menus +and reset them to the values contained in the +.Ev QUERY_STRING . +.It +Radio buttons to select pages either by name like in +.Xr man 1 +or using +.Xr apropos 1 +queries. +.It +A dropdown menu to optionally select a manual section. If one is provided, it has the same effect as the +.Xr man 1 +and .Xr apropos 1 .Fl s option. Otherwise, pages from all sections are shown. .It -An input box for an optional architecture name. +A dropdown menu to optionally select an architecture. If one is provided, it has the same effect as the +.Xr man 1 +and .Xr apropos 1 .Fl S option. @@ -67,12 +83,6 @@ If the configuration file .Pa /var/www/man/manpath.conf contains only one manpath, the dropdown menu is not shown. By default, the first manpath given in the file is used. -.It -A -.Dq Reset -button to undo any changes to the input boxes and the dropdown menu -and reset them to the values contained in the -.Ev QUERY_STRING . .El .Ss Program output The @@ -149,6 +159,67 @@ When using the .Xr slowcgi 8 proxy daemon is needed to translate FastCGI requests to plain old CGI. +.Pp +To compile +.Nm , +first copy +.Pa cgi.h.example +to +.Pa cgi.h +and edit it according to your needs. +It contains the following compile-time definitions: +.Bl -tag -width Ds +.It Ev COMPAT_OLDURI +Only useful for running on www.openbsd.org to deal with old URIs containing +.Qq "manpath=OpenBSD " +where the blank character has to be translated to a hyphen. +When compiling for other sites, this definition can be deleted. +.It Ev CSS_DIR +An optional path to the directory containing the CSS files, +to be specified relative to the server's document root, +and to be specified without a trailing slash. +When not specified, the CSS files +are assumed to be in the document root. +This is used in generated HTML code. +.It Ev CUSTOMIZE_BEGIN +A HTML string to be inserted right after opening the +.Aq BODY +element. +.It Ev CUSTOMIZE_TITLE +An ASCII string to be used for the HTML +.Aq TITLE +element. +.It Ev HTTP_HOST +The FQDN of the (possibly virtual) host the HTTP server is running on. +This is used for +.Ic Location: +headers in HTTP 303 responses. +.It Ev MAN_DIR +A path to the +.Nm +data directory to be used instead of +.Pa /var/www/man , +relative to the web server +.Xr chroot 2 +directory, to be specified without a trailing slash. +This is prepended to the manpath when opening +.Xr mandoc.db 5 +and manual page files. +.El +.Pp +After editing +.Pa cgi.h , +run +.Pp +.Dl make man.cgi +.Pp +and copy the files to the proper locations. +Reading the +.Cm installcgi +target in the +.Pa Makefile +can help with that, but do not run it without carefully checking it +because the directory layouts of web servers vary greatly. .Ss URI interface .Nm uniform resource identifiers are not needed for interactive use, @@ -165,77 +236,41 @@ The host name and a following slash. The path to the program, normally .Pa cgi-bin/man.cgi/ . .It -A page name, which can be -.Cm index , -which is the default and can be omitted, -.Cm search , -or -.Cm show . -.It -For -.Cm show -only, a slash, the manpath, another slash, +To show a single page, a slash, the manpath, another slash, and the name of the requested file, for example .Pa /OpenBSD-current/man1/mandoc.1 . .It -For -.Cm search -only, a query string starting with a question mark +For searches, a query string starting with a question mark and consisting of .Ar key Ns = Ns Ar value pairs, separated by ampersands, for example -.Pa ?manpath=OpenBSD-current&expr=mandoc . +.Pa ?manpath=OpenBSD-current&query=mandoc . Supported keys are .Cm manpath , -.Cm expr , +.Cm query , .Cm sec , -and .Cm arch , corresponding to .Xr apropos 1 .Fl M , .Ar expression , .Fl s , -and .Fl S , -respectively. +respectively, and +.Cm apropos , +which is a boolean parameter to select or deselect the +.Xr apropos 1 +query mode. For backward compatibility with the traditional .Nm , -.Cm query -is supported as an alias for -.Cm expr -and .Cm sektion -as an alias for +is supported as an alias for .Cm sec . .El .Sh ENVIRONMENT The web server may pass the following CGI variables to .Nm : .Bl -tag -width Ds -.It Ev CSS_DIR -An optional path to the directory containing the CSS files, -to be specified relative to the server's document root, -and to be specified without a trailing slash. -When not specified, the CSS files -are assumed to be in the document root. -This is used in generated HTML code. -.It Ev HTTP_HOST -The FQDN of the (possibly virtual) host the HTTP server is running on. -This is used for -.Ic Location: -headers in HTTP 303 responses. -.It Ev MAN_DIR -A path to the -.Nm -data directory to be used instead of -.Pa /man , -relative to the web server -.Xr chroot 2 -directory, to be specified without a trailing slash. -This is prepended to the manpath when opening -.Xr mandoc.db 5 -and manual page files. .It Ev PATH_INFO The final part of the URI path passed from the client to the server, starting after the @@ -291,6 +326,10 @@ Default data directory containing all the manual trees. Can be overridden by .Ev MAN_DIR . +.It Pa /man/mandoc/man1/apropos.1 , /man/mandoc/man8/man.cgi.8 +Manual pages documenting +.Nm +itself, linked from the index page. .It Pa /man/manpath.conf The list of available manpaths, one per line. .It Pa /man/OpenBSD-current/man1/mandoc.1 @@ -306,12 +345,20 @@ The CGI program is call-compatible with queries from the traditional .Pa man.cgi script by Wolfram Schneider. -However, the results may not be quite the same. +However, the output may not be quite the same. .Sh SEE ALSO .Xr apropos 1 , .Xr mandoc.db 5 , .Xr makewhatis 8 , .Xr slowcgi 8 +.Sh HISTORY +A version of +.Nm +based on +.Xr mandoc 1 +first appeared in mdocml-1.12.1 (March 2012). +The current SQLite3-based version first appeared in +.Ox 5.6 . .Sh AUTHORS .An -nosplit The