version 1.2, 2014/07/11 21:30:52 |
version 1.15, 2016/03/18 13:22:27 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" 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 |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
Line 37 At the top of each generated HTML page, |
|
Line 37 At the top of each generated HTML page, |
|
displays a search form containing these elements: |
displays a search form containing these elements: |
.Bl -enum |
.Bl -enum |
.It |
.It |
A |
An input box for search queries, expecting |
.Dq Search |
either a name of a manual page or an |
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 |
.Ar expression |
using the syntax described in the |
using the syntax described in the |
.Xr apropos 1 |
.Xr apropos 1 |
manual; filling this in is required for each search. |
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 |
.It |
An input box for an optional section number. |
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 |
|
.Xr apropos 1 |
|
queries. |
|
.It |
|
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 |
|
.Xr man 1 |
|
and |
.Xr apropos 1 |
.Xr apropos 1 |
.Fl s |
.Fl s |
option. |
option. |
Otherwise, pages from all sections are shown. |
Otherwise, pages from all sections are shown. |
.It |
.It |
An input box for an optional architecture name. |
A dropdown menu to optionally select an architecture. |
If one is provided, it has the same effect as the |
If one is provided, it has the same effect as the |
|
.Xr man 1 |
|
and |
.Xr apropos 1 |
.Xr apropos 1 |
.Fl S |
.Fl S |
option. |
option. |
Line 67 If the configuration file |
|
Line 89 If the configuration file |
|
.Pa /var/www/man/manpath.conf |
.Pa /var/www/man/manpath.conf |
contains only one manpath, the dropdown menu is not shown. |
contains only one manpath, the dropdown menu is not shown. |
By default, the first manpath given in the file is used. |
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 |
.El |
.Ss Program output |
.Ss Program output |
The |
The |
Line 145 database inside each manpath. |
|
Line 161 database inside each manpath. |
|
Configure your web server to execute CGI programs located in |
Configure your web server to execute CGI programs located in |
.Pa /cgi-bin . |
.Pa /cgi-bin . |
When using |
When using |
|
.Ox |
|
.Xr httpd 8 |
|
or |
.Xr nginx 8 , |
.Xr nginx 8 , |
the |
the |
.Xr slowcgi 8 |
.Xr slowcgi 8 |
proxy daemon is needed to translate FastCGI requests to plain old CGI. |
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 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 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 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 |
|
data directory relative to the web server |
|
.Xr chroot 2 |
|
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 |
|
.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 |
.Ss URI interface |
.Nm |
.Nm |
uniform resource identifiers are not needed for interactive use, |
uniform resource identifiers are not needed for interactive use, |
|
|
.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 , |
|
preceded by a slash unless empty. |
.It |
.It |
A page name, which can be |
To show a single page, a slash, the manpath, another slash, |
.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 |
and the name of the requested file, for example |
.Pa /OpenBSD-current/man1/mandoc.1 . |
.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 |
.It |
For |
For searches, a query string starting with a question mark |
.Cm search |
|
only, a query string starting with a question mark |
|
and consisting of |
and consisting of |
.Ar key Ns = Ns Ar value |
.Ar key Ns = Ns Ar value |
pairs, separated by ampersands, for example |
pairs, separated by ampersands, for example |
.Pa ?manpath=OpenBSD-current&expr=mandoc . |
.Pa ?manpath=OpenBSD-current&query=mandoc . |
Supported keys are |
Supported keys are |
.Cm manpath , |
.Cm manpath , |
.Cm expr , |
.Cm query , |
.Cm sec , |
.Cm sec , |
and |
|
.Cm arch , |
.Cm arch , |
corresponding to |
corresponding to |
.Xr apropos 1 |
.Xr apropos 1 |
.Fl M , |
.Fl M , |
.Ar expression , |
.Ar expression , |
.Fl s , |
.Fl s , |
and |
|
.Fl S , |
.Fl S , |
respectively. |
respectively, and |
|
.Cm apropos , |
|
which is a boolean parameter to select or deselect the |
|
.Xr apropos 1 |
|
query mode. |
For backward compatibility with the traditional |
For backward compatibility with the traditional |
.Nm , |
.Nm , |
.Cm query |
|
is supported as an alias for |
|
.Cm expr |
|
and |
|
.Cm sektion |
.Cm sektion |
as an alias for |
is supported as an alias for |
.Cm sec . |
.Cm sec . |
.El |
.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 all manpaths and 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 CSS_DIR |
.It Ev SCRIPT_NAME |
An optional path to the directory containing the CSS files, |
The initial part of the the URI passed from the client to the server, |
to be specified relative to the server's document root, |
starting after the server's host name and ending before |
and to be specified without a trailing slash. |
.Ev PATH_INFO . |
When not specified, the CSS files |
This is ignored by |
are assumed to be in the document root. |
.Nm . |
This is used in generated HTML code. |
When constructing URIs for links and redirections, the |
.It Ev HTTP_HOST |
.Dv SCRIPT_NAME |
The FQDN of the (possibly virtual) host the HTTP server is running on. |
preprocessor constant is used instead. |
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 |
.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 244 and ending before the |
|
Line 334 and ending before the |
|
.Ev QUERY_STRING . |
.Ev QUERY_STRING . |
It is used by the |
It is used by the |
.Cm show |
.Cm show |
page to aquire the manpath and filename it needs. |
page to acquire the manpath and filename it needs. |
.It Ev QUERY_STRING |
.It Ev QUERY_STRING |
The HTTP query string passed from the client to the server. |
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 the final part of the URI, after the question mark. |
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. |
|
.El |
.El |
.Sh FILES |
.Sh FILES |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
Line 267 Default web server |
|
Line 350 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/man-cgi.css |
.It Pa /htdocs/mandoc.css |
A style sheet for general |
|
.Nm |
|
styling, referenced from each generated HTML page. |
|
.It Pa /htdocs/man.css |
|
A style sheet for |
A style sheet for |
.Xr mandoc 1 |
.Xr mandoc 1 |
HTML styling, referenced from each generated HTML page after |
HTML styling, referenced from each generated HTML page. |
.Pa man-cgi.css . |
|
.It Pa /man |
.It Pa /man |
Default |
Default |
.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 |
|
Manual pages documenting |
|
.Nm |
|
itself, linked from the index page. |
.It Pa /man/manpath.conf |
.It Pa /man/manpath.conf |
The list of available manpaths, one per line. |
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 |
.It Pa /man/OpenBSD-current/man1/mandoc.1 |
An example |
An example |
.Xr mdoc 7 |
.Xr mdoc 7 |
|
|
CGI program is call-compatible with queries from the traditional |
CGI program is call-compatible with queries from the traditional |
.Pa man.cgi |
.Pa man.cgi |
script by Wolfram Schneider. |
script by Wolfram Schneider. |
However, the results may not be quite the same. |
However, the output may not be quite the same. |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr apropos 1 , |
.Xr apropos 1 , |
.Xr mandoc.db 5 , |
.Xr mandoc.db 5 , |