===================================================================
RCS file: /cvs/mandoc/man.cgi.8,v
retrieving revision 1.4
retrieving revision 1.14
diff -u -p -r1.4 -r1.14
--- mandoc/man.cgi.8	2014/07/13 00:19:51	1.4
+++ mandoc/man.cgi.8	2016/03/18 01:22:56	1.14
@@ -1,6 +1,6 @@
-.\"     $Id: man.cgi.8,v 1.4 2014/07/13 00:19:51 schwarze Exp $
+.\"     $Id: man.cgi.8,v 1.14 2016/03/18 01:22:56 schwarze Exp $
 .\"
-.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2014, 2015, 2016 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
@@ -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 13 2014 $
+.Dd $Mdocdate: March 18 2016 $
 .Dt MAN.CGI 8
 .Os
 .Sh NAME
@@ -43,6 +43,12 @@ either a name of a manual page or an
 using the syntax described in the
 .Xr apropos 1
 manual; filling this in is required for each search.
+.Pp
+The expression is broken into words at whitespace.
+Whitespace characters and backslashes can be escaped
+by prepending a backslash.
+The effect of prepending a backslash to another character is undefined;
+in the current implementation, it has no effect.
 .It
 A
 .Dq Submit
@@ -155,10 +161,68 @@ database inside each manpath.
 Configure your web server to execute CGI programs located in
 .Pa /cgi-bin .
 When using
+.Ox
+.Xr httpd 8
+or
 .Xr nginx 8 ,
 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_TITLE
+An ASCII string to be used for the HTML <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,
@@ -174,10 +238,19 @@ The host name and a following slash.
 .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.
 .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
+.Pf / Ar name Op \&. Ar sec
+.Sm on
 .It
 For searches, a query string starting with a question mark
 and consisting of
@@ -206,15 +279,38 @@ For backward compatibility with the traditional
 is supported as an alias for
 .Cm sec .
 .El
+.Ss Restricted character set
+For security reasons, in particular to prevent cross site scripting
+attacks, some strings used by
+.Nm
+can only contain the following characters:
+.Pp
+.Bl -dash -compact -offset indent
+.It
+lower case and upper case ASCII letters
+.It
+the ten decimal digits
+.It
+the dash
+.Pq Sq -
+.It
+the dot
+.Pq Sq \&.
+.It
+the slash
+.Pq Sq /
+.It
+the underscore
+.Pq Sq _
+.El
+.Pp
+In particular, this applies to the
+.Ev SCRIPT_NAME ,
+to all manpaths, and to all architecture names.
 .Sh ENVIRONMENT
 The web server may pass the following CGI variables to
 .Nm :
 .Bl -tag -width Ds
-.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 PATH_INFO
 The final part of the URI path passed from the client to the server,
 starting after the
@@ -223,7 +319,7 @@ and ending before the
 .Ev QUERY_STRING .
 It is used by the
 .Cm show
-page to aquire the manpath and filename it needs.
+page to acquire 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.
@@ -237,6 +333,10 @@ 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
@@ -255,50 +355,40 @@ Can be overridden by
 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
+.It Pa /htdocs/mandoc.css
 A style sheet for
 .Xr mandoc 1
-HTML styling, referenced from each generated HTML page after
-.Pa man-cgi.css .
+HTML styling, referenced from each generated HTML page.
 .It Pa /man
 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.
 .It Pa /man/manpath.conf
 The list of available manpaths, one per line.
+If any of the lines in this file contains a slash
+.Pq Sq /
+or any character not contained in the
+.Sx Restricted character set ,
+.Nm
+reports an internal server error and exits without doing anything.
+.It Pa /man/header.html
+An optional file containing static HTML code to be inserted right
+after opening the <BODY> element.
+.It Pa /man/footer.html
+An optional file containing static HTML code to be inserted right
+before closing the <BODY> element.
 .It Pa /man/OpenBSD-current/man1/mandoc.1
 An example
 .Xr mdoc 7
 source file located below the
 .Dq OpenBSD-current
 manpath.
-.El
-.Sh COMPILE-TIME DEFINES
-.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 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
 .Sh COMPATIBILITY
 The