version 1.14, 2016/03/18 01:22:56 |
version 1.17, 2016/05/28 13:40:49 |
|
|
CGI program searches for manual pages on a WWW server |
CGI program searches for manual pages on a WWW server |
and displays them to HTTP clients, |
and displays them to HTTP clients, |
providing functionality equivalent to the |
providing functionality equivalent to the |
.Xr apropos 1 |
|
and |
|
.Xr man 1 |
.Xr man 1 |
|
and |
|
.Xr apropos 1 |
utilities. |
utilities. |
It can use multiple manual trees in parallel. |
It can use multiple manual trees in parallel. |
.Ss HTML search interface |
.Ss HTML search interface |
Line 51 The effect of prepending a backslash to another charac |
|
Line 51 The effect of prepending a backslash to another charac |
|
in the current implementation, it has no effect. |
in the current implementation, it has no effect. |
.It |
.It |
A |
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 |
.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 |
.Xr apropos 1 |
queries. |
submit button. |
|
The string in the input box is interpreted as a search |
|
.Ar expression . |
.It |
.It |
A dropdown menu to optionally select a manual section. |
A dropdown menu to optionally select a manual section. |
If one is provided, it has the same effect as the |
If one is provided, it has the same effect as the |
Line 183 Only useful for running on www.openbsd.org to deal wit |
|
Line 178 Only useful for running on www.openbsd.org to deal wit |
|
.Qq "manpath=OpenBSD " |
.Qq "manpath=OpenBSD " |
where the blank character has to be translated to a hyphen. |
where the blank character has to be translated to a hyphen. |
When compiling for other sites, this definition can be deleted. |
When compiling for other sites, this definition can be deleted. |
.It Ev CSS_DIR |
.It Dv CSS_DIR |
An optional path to the directory containing the CSS files, |
An optional file system path to the directory containing the file |
|
.Pa mandoc.css , |
to be specified relative to the server's document root, |
to be specified relative to the server's document root, |
and to be specified without a trailing slash. |
and to be specified without a trailing slash. |
When not specified, the CSS files |
When empty, the CSS file is assumed to be in the document root. |
are assumed to be in the document root. |
Otherwise, a leading slash is needed. |
This is used in generated HTML code. |
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. |
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. |
The FQDN of the (possibly virtual) host the HTTP server is running on. |
This is used for |
This is used for |
.Ic Location: |
.Ic Location: |
headers in HTTP 303 responses. |
headers in HTTP 303 responses. |
.It Ev MAN_DIR |
.It Dv MAN_DIR |
A path to the |
A file system path to the |
.Nm |
.Nm |
data directory to be used instead of |
data directory relative to the web server |
.Pa /var/www/man , |
|
relative to the web server |
|
.Xr chroot 2 |
.Xr chroot 2 |
directory, to be specified without a trailing slash. |
directory, to be specified with a leading slash and without a trailing slash. |
This is prepended to the manpath when opening |
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 |
.Xr mandoc.db 5 |
and manual page files. |
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 |
.El |
.Pp |
.Pp |
After editing |
After editing |
|
|
.Cm http:// |
.Cm http:// |
protocol specifier. |
protocol specifier. |
.It |
.It |
The host name and a following slash. |
The host name. |
.It |
.It |
The path to the program, normally |
The |
.Pa cgi-bin/man.cgi/ . |
.Dv SCRIPT_NAME , |
On |
preceded by a slash unless empty. |
.Lk http://man.openbsd.org/ , |
|
.Xr httpd 8 |
|
is configured such that the path to the program can be omitted. |
|
.It |
.It |
To show a single page, a slash, the manpath, another slash, |
To show a single page, a slash, the manpath, another slash, |
and the name of the requested file, for example |
and the name of the requested file, for example |
|
|
.Pq Sq _ |
.Pq Sq _ |
.El |
.El |
.Pp |
.Pp |
In particular, this applies to the |
In particular, this applies to all manpaths and architecture names. |
.Ev SCRIPT_NAME , |
|
to all manpaths, and to all architecture names. |
|
.Sh ENVIRONMENT |
.Sh ENVIRONMENT |
The web server may pass the following CGI variables to |
The web server may pass the following CGI variables to |
.Nm : |
.Nm : |
.Bl -tag -width Ds |
.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 |
.It Ev PATH_INFO |
The final part of the URI path passed from the client to the server, |
The final part of the URI path passed from the client to the server, |
starting after the |
starting after the |
Line 326 It is the final part of the URI, after the question ma |
|
Line 336 It is the final part of the URI, after the question ma |
|
It is used by the |
It is used by the |
.Cm search |
.Cm search |
page to acquire the named parameters it needs. |
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 |
.El |
.Sh FILES |
.Sh FILES |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
Line 346 Default web server |
|
Line 345 Default web server |
|
directory. |
directory. |
All the following paths are specified relative to this directory. |
All the following paths are specified relative to this directory. |
.It Pa /cgi-bin/man.cgi |
.It Pa /cgi-bin/man.cgi |
The path to the |
The usual file system path to the |
.Nm |
.Nm |
program relative to the server root. |
program inside the web server |
Can be overridden by |
.Xr chroot 2 |
.Ev SCRIPT_NAME . |
directory. |
|
A different name can be chosen, but in any case, it needs to be configured in |
|
.Xr httpd.conf 5 . |
.It Pa /htdocs |
.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 |
This is part of the web server configuration and not specific to |
.Nm . |
.Nm . |
.It Pa /htdocs/mandoc.css |
.It Pa /htdocs/mandoc.css |
|
|
.Nm |
.Nm |
data directory containing all the manual trees. |
data directory containing all the manual trees. |
Can be overridden by |
Can be overridden by |
.Ev MAN_DIR . |
.Dv MAN_DIR . |
.It Pa /man/mandoc/man1/apropos.1 , /man/mandoc/man8/man.cgi.8 |
.It Pa /man/mandoc/man1/apropos.1 , /man/mandoc/man8/man.cgi.8 |
Manual pages documenting |
Manual pages documenting |
.Nm |
.Nm |