=================================================================== RCS file: /cvs/mandoc/man.cgi.8,v retrieving revision 1.14 retrieving revision 1.23 diff -u -p -r1.14 -r1.23 --- mandoc/man.cgi.8 2016/03/18 01:22:56 1.14 +++ mandoc/man.cgi.8 2018/05/20 21:48:44 1.23 @@ -1,4 +1,4 @@ -.\" $Id: man.cgi.8,v 1.14 2016/03/18 01:22:56 schwarze Exp $ +.\" $Id: man.cgi.8,v 1.23 2018/05/20 21:48:44 schwarze Exp $ .\" .\" Copyright (c) 2014, 2015, 2016 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: March 18 2016 $ +.Dd $Mdocdate: May 20 2018 $ .Dt MAN.CGI 8 .Os .Sh NAME @@ -26,9 +26,9 @@ The CGI program searches for manual pages on a WWW server and displays them to HTTP clients, providing functionality equivalent to the -.Xr apropos 1 -and .Xr man 1 +and +.Xr apropos 1 utilities. It can use multiple manual trees in parallel. .Ss HTML search interface @@ -51,20 +51,15 @@ The effect of prepending a backslash to another charac in the current implementation, it has no effect. .It 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 +submit button. +The string in the input box is interpreted as the name of a manual page. +.It +An .Xr apropos 1 -queries. +submit button. +The string in the input box is interpreted as a search +.Ar expression . .It A dropdown menu to optionally select a manual section. If one is provided, it has the same effect as the @@ -109,6 +104,9 @@ Lists are returned when searches match more than one m The first column shows the names and section numbers of manuals as clickable links. The second column shows the one-line descriptions of the manuals. +For +.Xr man 1 +style searches, the content of the first manual page follows the list. .It A manual page. This output format is used when a search matches exactly one manual page, or when a link on a list page or an @@ -116,7 +114,7 @@ manual page, or when a link on a list page or an link on another manual page is followed. .It A no-result page. This is shown when a search request returns no results - -eiher because it violates the query syntax, or because +either because it violates the query syntax, or because the search does not match any manual pages. .It \&An error page. This cannot happen by merely clicking the @@ -162,9 +160,7 @@ Configure your web server to execute CGI programs loca .Pa /cgi-bin . When using .Ox -.Xr httpd 8 -or -.Xr nginx 8 , +.Xr httpd 8 , the .Xr slowcgi 8 proxy daemon is needed to translate FastCGI requests to plain old CGI. @@ -183,31 +179,37 @@ Only useful for running on www.openbsd.org to deal wit .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, +.It Dv CSS_DIR +An optional file system path to the directory containing the file +.Pa mandoc.css , 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. +When empty, the CSS file is assumed to be in the document root. +Otherwise, a leading slash is needed. This is used in generated HTML code. -.It Ev CUSTOMIZE_TITLE +.It Dv CUSTOMIZE_TITLE An ASCII string to be used for the HTML 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 +.It Dv MAN_DIR +A file system path to the .Nm -data directory to be used instead of -.Pa /var/www/man , -relative to the web server +data directory relative to the web server .Xr chroot 2 -directory, to be specified without a trailing slash. -This is prepended to the manpath when opening +directory, to be specified with a leading slash and without a trailing slash. +It needs to have at least one component; the root directory cannot be used +for this purpose. +The files +.Pa manpath.conf , +.Pa header.html , +and +.Pa footer.html +are looked up in this directory. +It is also prepended to the manpath when opening .Xr mandoc.db 5 and manual page files. +.It Dv SCRIPT_NAME +The initial component of URIs, to be specified without leading +and trailing slashes. +It can be empty. .El .Pp After editing @@ -216,13 +218,16 @@ 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. +and copy the resulting binary to the proper location, +for example using the command: +.Pp +.Dl make installcgi +.Pp +In addition to that, make sure the default manpath contains the files +.Pa man1/apropos.1 +and +.Pa man8/man.cgi.8 , +or the documentation links at the bottom of the index page will not work. .Ss URI interface .Nm uniform resource identifiers are not needed for interactive use, @@ -232,23 +237,24 @@ They consist of: .It The .Cm http:// +or +.Cm https:// protocol specifier. .It -The host name and a following slash. +The host name. .It -The path to the program, normally -.Pa cgi-bin/man.cgi/ . -On -.Lk http://man.openbsd.org/ , -.Xr httpd 8 -is configured such that the path to the program can be omitted. +The +.Dv SCRIPT_NAME , +preceded by a slash unless empty. .It 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 . This can be abbreviated according to the following syntax: .Sm off -.Op / Ar manpath Oo / Cm man Ar sec Oc Op / Ar arch +.Op / Ar manpath +.Op / Cm man Ar sec +.Op / Ar arch .Pf / Ar name Op \&. Ar sec .Sm on .It @@ -304,13 +310,20 @@ the underscore .Pq Sq _ .El .Pp -In particular, this applies to the -.Ev SCRIPT_NAME , -to all manpaths, and to all architecture names. +In particular, this applies to all manpaths and architecture names. .Sh ENVIRONMENT The web server may pass the following CGI variables to .Nm : .Bl -tag -width Ds +.It Ev SCRIPT_NAME +The initial part of the URI passed from the client to the server, +starting after the server's host name and ending before +.Ev PATH_INFO . +This is ignored by +.Nm . +When constructing URIs for links and redirections, the +.Dv SCRIPT_NAME +preprocessor constant is used instead. .It Ev PATH_INFO The final part of the URI path passed from the client to the server, starting after the @@ -326,17 +339,6 @@ It is the final part of the URI, after the question ma It is used by the .Cm search page to acquire the named parameters it needs. -.It Ev SCRIPT_NAME -The path to the -.Nm -binary relative to the server root, usually -.Pa /cgi-bin/man.cgi . -This is used for generating URIs to be embedded -in generated HTML code and HTTP headers. -If this contains any character not contained in the -.Sx Restricted character set , -.Nm -reports an internal server error and exits without doing anything. .El .Sh FILES .Bl -tag -width Ds @@ -346,13 +348,18 @@ Default web server directory. All the following paths are specified relative to this directory. .It Pa /cgi-bin/man.cgi -The path to the +The usual file system path to the .Nm -program relative to the server root. -Can be overridden by -.Ev SCRIPT_NAME . +program inside the web server +.Xr chroot 2 +directory. +A different name can be chosen, but in any case, it needs to be configured in +.Xr httpd.conf 5 . .It Pa /htdocs -The path to the server document root relative to the server root. +The file system path to the server document root directory +relative to the server +.Xr chroot 2 +directory. This is part of the web server configuration and not specific to .Nm . .It Pa /htdocs/mandoc.css @@ -364,11 +371,7 @@ Default .Nm 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. +.Dv MAN_DIR . .It Pa /man/manpath.conf The list of available manpaths, one per line. If any of the lines in this file contains a slash @@ -396,7 +399,7 @@ The CGI program is call-compatible with queries from the traditional .Pa man.cgi script by Wolfram Schneider. -However, the output may not be quite the same. +However, the output looks quite different. .Sh SEE ALSO .Xr apropos 1 , .Xr mandoc.db 5 , @@ -408,15 +411,16 @@ A version of 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 . +The current +.Xr mandoc.db 5 +database format first appeared in +.Ox 6.1 . .Sh AUTHORS .An -nosplit The .Nm program was written by .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv -and ported to the SQLite3-based -.Xr mandoc.db 5 -backend by -.An Ingo Schwarze Aq Mt schwarze@openbsd.org . +and is maintained by +.An Ingo Schwarze Aq Mt schwarze@openbsd.org , +who also designed and implemented the database format.