during prioritization for man(1), correctly extract the section name

[mandoc.git] / man.cgi.8

diff --git a/man.cgi.8 b/man.cgi.8
index 05a374d090b8aa2e287eff339f53036c39078469..b8cd623c598d87672f643f71fab10afa36ba4508 100644 (file)
--- a/man.cgi.8
+++ b/man.cgi.8
@@ -1,4 +1,4 @@
-.\"     $Id: man.cgi.8,v 1.16 2016/03/19 13:29:22 schwarze Exp $
+.\"    $Id: man.cgi.8,v 1.23 2018/05/20 21:48:44 schwarze Exp $
 .\"
 .\" Copyright (c) 2014, 2015, 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -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 19 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 character is undefined;
 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 manual page.
 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 located in
 .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.
@@ -193,11 +189,6 @@ Otherwise, a leading slash is needed.
 This is used in generated HTML code.
 .It Dv CUSTOMIZE_TITLE
 An ASCII string to be used for the HTML <TITLE> element.
-.It Dv 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 Dv MAN_DIR
 A file system path to the
 .Nm
@@ -227,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,
@@ -243,6 +237,8 @@ They consist of:
 .It
 The
 .Cm http://
+or
+.Cm https://
 protocol specifier.
 .It
 The host name.
@@ -256,7 +252,9 @@ 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
@@ -374,10 +372,6 @@ Default
 data directory containing all the manual trees.
 Can be overridden by
 .Dv 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.
 If any of the lines in this file contains a slash
@@ -405,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 ,
@@ -417,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.