Full rewrite of the man.cgi(8) manual.

Almost everything in the old man.cgi(7) was outdated in one way
or another - catman, catman.conf, CACHE_DIR, /cache, manroots,
replacing '/' with spaces, /tmp...

Instead, document the HTML and URI interfaces, the output and the setup,
and complete the listings of ENVIRONMENT variables and FILES.

Using section 8 instead of section 7 because that's the usual place
for CGI programs, see for example bgplg(8) and slowcgi(8).

3 files changed, 327 insertions, 125 deletions

diff --git a/Makefile b/Makefile
index 589a3256..5744b1bf 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-# $Id: Makefile,v 1.421 2014/07/09 07:30:47 schwarze Exp $
+# $Id: Makefile,v 1.422 2014/07/10 00:31:10 schwarze Exp $
 #
 # Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 # Copyright (c) 2011, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -134,7 +134,7 @@ SRCS		 = LICENSE \
 		   makewhatis.8 \
 		   man.7 \
 		   man.c \
-		   man.cgi.7 \
+		   man.cgi.8 \
 		   man-cgi.css \
 		   man.h \
 		   man_hash.c \
@@ -317,12 +317,12 @@ WWW_MANS	 = apropos.1.html \
 		   mandoc.db.5.html \
 		   eqn.7.html \
 		   man.7.html \
-		   man.cgi.7.html \
 		   mandoc_char.7.html \
 		   mdoc.7.html \
 		   roff.7.html \
 		   tbl.7.html \
 		   makewhatis.8.html \
+		   man.cgi.8.html \
 		   man.h.html \
 		   mandoc.h.html \
 		   mandoc_aux.h.html \
diff --git a/man.cgi.7 b/man.cgi.7
deleted file mode 100644
index 74937a68..00000000
--- a/man.cgi.7
+++ /dev/null
@@ -1,122 +0,0 @@
-.Dd $Mdocdate: April 18 2014 $
-.Dt MAN.CGI 7
-.Os
-.Sh NAME
-.Nm man.cgi
-.Nd cgi for manpage query and display
-.Sh SYNOPSIS
-.Nm
-.Sh DESCRIPTION
-The
-.Nm
-script queries and displays manual pages.
-It interfaces with
-.Xr makewhatis 8
-databases cached with
-.Xr catman 8 .
-.Pp
-To use
-.Nm ,
-create a manual cache in
-.Xr catman 8 .
-Assign this directory to the environment variable
-.Ev CACHE_DIR ,
-defaulting to
-.Pa /cache/man.cgi .
-Copy the
-.Pa man.cgi
-script into your CGI directory (see
-.Sx FILES
-for other relevant files).
-.Pp
-Multiple
-.Xr catman 8
-trees may be managed by
-.Nm :
-directories under
-.Ev CACHE_DIR
-containing
-.Pa etc/catman.conf
-are identified as
-.Qq manroots .
-The path of a manroot under
-.Ev CACHE_DIR
-is converted to a name by replacing path separators with spaces.
-.Pp
-Thus, if
-.Ev CACHE_DIR
-is the default
-.Pa /cache/man.cgi ,
-the web-server is jailed to
-.Pa /var/www ,
-and cache subdirectories
-.Pa ./foo/1
-and
-.Pa ./bar/2
-contain
-.Pa etc/catman.conf ,
-.Nm
-will assign these to manroots
-.Qq foo 1
-and
-.Qq bar 2 ,
-respectively.
-These names will appear as choices when searching for manuals.
-.Pp
-If
-.Nm
-finds only one manroot, or none, then the selection box is omitted.
-If no manroot is specified during search, the first manroot is used by
-default.
-.Sh ENVIRONMENT
-.Bl -tag -width Ds
-.It Ev CACHE_DIR
-The absolute path of the
-.Xr catman 8
-cache directory.
-This must not have a trailing slash.
-.It Ev CSS_DIR
-Prepended to CSS file links in outputted HTML files.
-This must not have a trailing slash.
-.El
-.Sh FILES
-.Bl -tag -width Ds
-.It Pa etc/catman.conf
-Built by
-.Xr catman 8
-and must exist at least once under the configuration directory root.
-.It Pa man.css
-Should be visible in the server document root or within
-.Ev CSS_DIR .
-Included in each page after
-.Pa man-cgi.css ,
-ostensibly for
-.Xr mandoc 1
-HTML output styling.
-.It Pa man.cgi.css
-Should be visible in the server document root or within
-.Ev CSS_DIR .
-Included in each page, ostensibly for general
-.Nm
-styling.
-.El
-.Sh COMPATIBILITY
-The
-.Nm
-script is call-compatible with queries from the traditional
-.Pa man.cgi
-script by Wolfram Schneider.
-However, the results may not be quite the same.
-.Sh SEE ALSO
-.Xr catman 8 ,
-.Xr makewhatis 8
-.Sh AUTHORS
-The
-.Nm
-utility was written by
-.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
-.Sh CAVEATS
-If you're running in a jailed web-server, make sure the
-.Pa /tmp
-directory exists and is writable.
-The databases may need this for scratch space.
diff --git a/man.cgi.8 b/man.cgi.8
new file mode 100644
index 00000000..eed0560d
--- /dev/null
+++ b/man.cgi.8
@@ -0,0 +1,324 @@
+.\"     $Id: man.cgi.8,v 1.1 2014/07/10 00:31:10 schwarze Exp $
+.\"
+.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" 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 $
+.Dt MAN.CGI 8
+.Os
+.Sh NAME
+.Nm man.cgi
+.Nd CGI program to search and display manual pages
+.Sh DESCRIPTION
+The
+.Nm
+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
+utilities.
+It can use multiple manual trees in parallel.
+.Ss HTML search interface
+At the top of each generated HTML page,
+.Nm
+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
+.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.
+If one is provided, it has the same effect as the
+.Xr apropos 1
+.Fl s
+option.
+Otherwise, pages from all sections are shown.
+.It
+An input box for an optional architecture name.
+If one is provided, it has the same effect as the
+.Xr apropos 1
+.Fl S
+option.
+By default, pages for all architectures are shown.
+.It
+A dropdown menu to select a manual tree.
+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
+.Nm
+program generates five kinds of output pages:
+.Bl -tag -width Ds
+.It The index page.
+This is returned when calling
+.Nm
+without
+.Ev PATH_INFO
+and without a
+.Ev QUERY_STRING .
+It serves as a starting point for using the program
+and shows the search form only.
+.It A list page.
+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.
+.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
+.Ic \&Xr
+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
+the search does not match any manual pages.
+.It \&An error page.
+This cannot happen by merely clicking the
+.Dq Search
+button, but only by manually entering an invalid URI.
+It does not show the search form, but only an error message
+and a link back to the index page.
+.El
+.Ss Setup
+For each manual tree, create one first-level subdirectory below
+.Pa /var/www/man .
+The name of one of these directories is called a
+.Dq manpath
+in the context of
+.Nm .
+Create a single ASCII text file
+.Pa /var/www/man/manpath.conf
+containing the names of these directories, one per line.
+The directory given first is used as the default manpath.
+.Pp
+Inside each of these directories, use the same directory and file
+structure as found below
+.Pa /usr/share/man ,
+that is, second-level subdirectories
+.Pa /var/www/man/*/man1 , /var/www/man/*/man2
+etc. containing source
+.Xr mdoc 7
+and
+.Xr man 7
+manuals with file name extensions matching the section numbers,
+second-level subdirectories
+.Pa /var/www/man/*/cat1 , /var/www/man/*/cat2
+etc. containing preformatted manuals with the file name extension
+.Sq 0 ,
+and optional third-level subdirectories for architectures.
+Use
+.Xr makewhatis 8
+to create a
+.Xr mandoc.db 5
+database inside each manpath.
+.Pp
+Configure your web server to execute CGI programs located in
+.Pa /cgi-bin .
+When using
+.Xr nginx 8 ,
+the
+.Xr slowcgi 8
+proxy daemon is needed to translate FastCGI requests to plain old CGI.
+.Ss URI interface
+.Nm
+uniform resource identifiers are not needed for interactive use,
+but can be useful for deep linking.
+They consist of:
+.Bl -enum
+.It
+The
+.Cm http://
+protocol specifier.
+.It
+The host name and a following slash.
+.It
+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,
+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
+and consisting of
+.Ar key Ns = Ns Ar value
+pairs, separated by ampersands, for example
+.Pa ?manpath=OpenBSD-current&expr=mandoc .
+Supported keys are
+.Cm manpath ,
+.Cm expr ,
+.Cm sec ,
+and
+.Cm arch ,
+corresponding to
+.Xr apropos 1
+.Fl M ,
+.Ar expression ,
+.Fl s ,
+and
+.Fl S ,
+respectively.
+For backward compatibility with the traditional
+.Nm ,
+.Cm query
+is supported as an alias for
+.Cm expr
+and
+.Cm sektion
+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
+.Ev SCRIPT_NAME
+and ending before the
+.Ev QUERY_STRING .
+It is used by the
+.Cm show
+page to aquire the manpath and filename it needs.
+.It Ev QUERY_STRING
+The HTTP query string passed from the client to the server.
+It is the final part of the URI, after the question mark.
+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.
+.El
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa /var/www
+Default web server
+.Xr chroot 2
+directory.
+All the following paths are specified relative to this directory.
+.It Pa /cgi-bin/man.cgi
+The path to the
+.Nm
+program relative to the server root.
+Can be overridden by
+.Ev SCRIPT_NAME .
+.It Pa /htdocs
+The path to the server document root relative to the server root.
+This is part of the web server configuration and not specific to
+.Nm .
+.It Pa /htdocs/man-cgi.css
+A style sheet for general
+.Nm
+styling, referenced from each generated HTML page.
+.It Pa /htdocs/man.css
+A style sheet for
+.Xr mandoc 1
+HTML styling, referenced from each generated HTML page after
+.Pa man-cgi.css .
+.It Pa /man
+Default
+.Nm
+data directory containing all the manual trees.
+Can be overridden by
+.Ev MAN_DIR .
+.It Pa /man/manpath.conf
+The list of available manpaths, one per line.
+.It Pa /man/OpenBSD-current/man1/mandoc.1
+An example
+.Xr mdoc 7
+source file located below the
+.Dq OpenBSD-current
+manpath.
+.El
+.Sh COMPATIBILITY
+The
+.Nm
+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.
+.Sh SEE ALSO
+.Xr apropos 1 ,
+.Xr mandoc.db 5 ,
+.Xr makewhatis 8 ,
+.Xr slowcgi 8
+.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 .