summaryrefslogtreecommitdiffstats
path: root/man.cgi.8
diff options
context:
space:
mode:
authorIngo Schwarze <schwarze@openbsd.org>2016-03-18 13:22:27 +0000
committerIngo Schwarze <schwarze@openbsd.org>2016-03-18 13:22:27 +0000
commitd4eefc24c396ab1dee0b161ee7da851aecc16c36 (patch)
treebe98aa40817013838c05b5c82eecd873ca9f7951 /man.cgi.8
parent0fa45817cf7eb87f808a954fb566fa6683a19d3f (diff)
downloadmandoc-d4eefc24c396ab1dee0b161ee7da851aecc16c36.tar.gz
Make the SCRIPT_NAME logic simpler, safer, and make it actually work;
in part based on ideas by bentley@. While here, improve the documentation.
Diffstat (limited to 'man.cgi.8')
-rw-r--r--man.cgi.889
1 files changed, 49 insertions, 40 deletions
diff --git a/man.cgi.8 b/man.cgi.8
index adc483a8..819bb391 100644
--- a/man.cgi.8
+++ b/man.cgi.8
@@ -183,31 +183,42 @@ 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,
+.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 <TITLE> element.
-.It Ev HTTP_HOST
+.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 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
@@ -234,14 +245,11 @@ The
.Cm http://
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
@@ -304,13 +312,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 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 +341,6 @@ 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.
-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 +350,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,7 +373,7 @@ Default
.Nm
data directory containing all the manual trees.
Can be overridden by
-.Ev MAN_DIR .
+.Dv MAN_DIR .
.It Pa /man/mandoc/man1/apropos.1 , /man/mandoc/man8/man.cgi.8
Manual pages documenting
.Nm