xref: /openbsd-src/usr.bin/mandoc/man.cgi.8 (revision ae3cb403620ab940fbaabb3055fac045a63d56b7)
1.\"	$OpenBSD: man.cgi.8,v 1.21 2017/03/18 16:48:07 schwarze Exp $
2.\"
3.\" Copyright (c) 2014, 2015, 2016 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: March 18 2017 $
18.Dt MAN.CGI 8
19.Os
20.Sh NAME
21.Nm man.cgi
22.Nd CGI program to search and display manual pages
23.Sh DESCRIPTION
24The
25.Nm
26CGI program searches for manual pages on a WWW server
27and displays them to HTTP clients,
28providing functionality equivalent to the
29.Xr man 1
30and
31.Xr apropos 1
32utilities.
33It can use multiple manual trees in parallel.
34.Ss HTML search interface
35At the top of each generated HTML page,
36.Nm
37displays a search form containing these elements:
38.Bl -enum
39.It
40An input box for search queries, expecting
41either a name of a manual page or an
42.Ar expression
43using the syntax described in the
44.Xr apropos 1
45manual; filling this in is required for each search.
46.Pp
47The expression is broken into words at whitespace.
48Whitespace characters and backslashes can be escaped
49by prepending a backslash.
50The effect of prepending a backslash to another character is undefined;
51in the current implementation, it has no effect.
52.It
53A
54.Xr man 1
55submit button.
56The string in the input box is interpreted as the name of a manual page.
57.It
58An
59.Xr apropos 1
60submit button.
61The string in the input box is interpreted as a search
62.Ar expression .
63.It
64A dropdown menu to optionally select a manual section.
65If one is provided, it has the same effect as the
66.Xr man 1
67and
68.Xr apropos 1
69.Fl s
70option.
71Otherwise, pages from all sections are shown.
72.It
73A dropdown menu to optionally select an architecture.
74If one is provided, it has the same effect as the
75.Xr man 1
76and
77.Xr apropos 1
78.Fl S
79option.
80By default, pages for all architectures are shown.
81.It
82A dropdown menu to select a manual tree.
83If the configuration file
84.Pa /var/www/man/manpath.conf
85contains only one manpath, the dropdown menu is not shown.
86By default, the first manpath given in the file is used.
87.El
88.Ss Program output
89The
90.Nm
91program generates five kinds of output pages:
92.Bl -tag -width Ds
93.It The index page.
94This is returned when calling
95.Nm
96without
97.Ev PATH_INFO
98and without a
99.Ev QUERY_STRING .
100It serves as a starting point for using the program
101and shows the search form only.
102.It A list page.
103Lists are returned when searches match more than one manual page.
104The first column shows the names and section numbers of manuals
105as clickable links.
106The second column shows the one-line descriptions of the manuals.
107.It A manual page.
108This output format is used when a search matches exactly one
109manual page, or when a link on a list page or an
110.Ic \&Xr
111link on another manual page is followed.
112.It A no-result page.
113This is shown when a search request returns no results -
114eiher because it violates the query syntax, or because
115the search does not match any manual pages.
116.It \&An error page.
117This cannot happen by merely clicking the
118.Dq Search
119button, but only by manually entering an invalid URI.
120It does not show the search form, but only an error message
121and a link back to the index page.
122.El
123.Ss Setup
124For each manual tree, create one first-level subdirectory below
125.Pa /var/www/man .
126The name of one of these directories is called a
127.Dq manpath
128in the context of
129.Nm .
130Create a single ASCII text file
131.Pa /var/www/man/manpath.conf
132containing the names of these directories, one per line.
133The directory given first is used as the default manpath.
134.Pp
135Inside each of these directories, use the same directory and file
136structure as found below
137.Pa /usr/share/man ,
138that is, second-level subdirectories
139.Pa /var/www/man/*/man1 , /var/www/man/*/man2
140etc. containing source
141.Xr mdoc 7
142and
143.Xr man 7
144manuals with file name extensions matching the section numbers,
145second-level subdirectories
146.Pa /var/www/man/*/cat1 , /var/www/man/*/cat2
147etc. containing preformatted manuals with the file name extension
148.Sq 0 ,
149and optional third-level subdirectories for architectures.
150Use
151.Xr makewhatis 8
152to create a
153.Xr mandoc.db 5
154database inside each manpath.
155.Pp
156Configure your web server to execute CGI programs located in
157.Pa /cgi-bin .
158When using
159.Ox
160.Xr httpd 8 ,
161the
162.Xr slowcgi 8
163proxy daemon is needed to translate FastCGI requests to plain old CGI.
164.Pp
165To compile
166.Nm ,
167first copy
168.Pa cgi.h.example
169to
170.Pa cgi.h
171and edit it according to your needs.
172It contains the following compile-time definitions:
173.Bl -tag -width Ds
174.It Ev COMPAT_OLDURI
175Only useful for running on www.openbsd.org to deal with old URIs containing
176.Qq "manpath=OpenBSD "
177where the blank character has to be translated to a hyphen.
178When compiling for other sites, this definition can be deleted.
179.It Dv CSS_DIR
180An optional file system path to the directory containing the file
181.Pa mandoc.css ,
182to be specified relative to the server's document root,
183and to be specified without a trailing slash.
184When empty, the CSS file is assumed to be in the document root.
185Otherwise, a leading slash is needed.
186This is used in generated HTML code.
187.It Dv CUSTOMIZE_TITLE
188An ASCII string to be used for the HTML <TITLE> element.
189.It Dv MAN_DIR
190A file system path to the
191.Nm
192data directory relative to the web server
193.Xr chroot 2
194directory, to be specified with a leading slash and without a trailing slash.
195It needs to have at least one component; the root directory cannot be used
196for this purpose.
197The files
198.Pa manpath.conf ,
199.Pa header.html ,
200and
201.Pa footer.html
202are looked up in this directory.
203It is also prepended to the manpath when opening
204.Xr mandoc.db 5
205and manual page files.
206.It Dv SCRIPT_NAME
207The initial component of URIs, to be specified without leading
208and trailing slashes.
209It can be empty.
210.El
211.Pp
212After editing
213.Pa cgi.h ,
214run
215.Pp
216.Dl make man.cgi
217.Pp
218and copy the resulting binary to the proper location,
219for example using the command:
220.Pp
221.Dl make installcgi
222.Pp
223In addition to that, make sure the default manpath contains the files
224.Pa man1/apropos.1
225and
226.Pa man8/man.cgi.8 ,
227or the documentation links at the bottom of the index page will not work.
228.Ss URI interface
229.Nm
230uniform resource identifiers are not needed for interactive use,
231but can be useful for deep linking.
232They consist of:
233.Bl -enum
234.It
235The
236.Cm http://
237protocol specifier.
238.It
239The host name.
240.It
241The
242.Dv SCRIPT_NAME ,
243preceded by a slash unless empty.
244.It
245To show a single page, a slash, the manpath, another slash,
246and the name of the requested file, for example
247.Pa /OpenBSD-current/man1/mandoc.1 .
248This can be abbreviated according to the following syntax:
249.Sm off
250.Op / Ar manpath
251.Op / Cm man Ar sec
252.Op / Ar arch
253.Pf / Ar name Op \&. Ar sec
254.Sm on
255.It
256For searches, a query string starting with a question mark
257and consisting of
258.Ar key Ns = Ns Ar value
259pairs, separated by ampersands, for example
260.Pa ?manpath=OpenBSD-current&query=mandoc .
261Supported keys are
262.Cm manpath ,
263.Cm query ,
264.Cm sec ,
265.Cm arch ,
266corresponding to
267.Xr apropos 1
268.Fl M ,
269.Ar expression ,
270.Fl s ,
271.Fl S ,
272respectively, and
273.Cm apropos ,
274which is a boolean parameter to select or deselect the
275.Xr apropos 1
276query mode.
277For backward compatibility with the traditional
278.Nm ,
279.Cm sektion
280is supported as an alias for
281.Cm sec .
282.El
283.Ss Restricted character set
284For security reasons, in particular to prevent cross site scripting
285attacks, some strings used by
286.Nm
287can only contain the following characters:
288.Pp
289.Bl -dash -compact -offset indent
290.It
291lower case and upper case ASCII letters
292.It
293the ten decimal digits
294.It
295the dash
296.Pq Sq -
297.It
298the dot
299.Pq Sq \&.
300.It
301the slash
302.Pq Sq /
303.It
304the underscore
305.Pq Sq _
306.El
307.Pp
308In particular, this applies to all manpaths and architecture names.
309.Sh ENVIRONMENT
310The web server may pass the following CGI variables to
311.Nm :
312.Bl -tag -width Ds
313.It Ev SCRIPT_NAME
314The initial part of the URI passed from the client to the server,
315starting after the server's host name and ending before
316.Ev PATH_INFO .
317This is ignored by
318.Nm .
319When constructing URIs for links and redirections, the
320.Dv SCRIPT_NAME
321preprocessor constant is used instead.
322.It Ev PATH_INFO
323The final part of the URI path passed from the client to the server,
324starting after the
325.Ev SCRIPT_NAME
326and ending before the
327.Ev QUERY_STRING .
328It is used by the
329.Cm show
330page to acquire the manpath and filename it needs.
331.It Ev QUERY_STRING
332The HTTP query string passed from the client to the server.
333It is the final part of the URI, after the question mark.
334It is used by the
335.Cm search
336page to acquire the named parameters it needs.
337.El
338.Sh FILES
339.Bl -tag -width Ds
340.It Pa /var/www
341Default web server
342.Xr chroot 2
343directory.
344All the following paths are specified relative to this directory.
345.It Pa /cgi-bin/man.cgi
346The usual file system path to the
347.Nm
348program inside the web server
349.Xr chroot 2
350directory.
351A different name can be chosen, but in any case, it needs to be configured in
352.Xr httpd.conf 5 .
353.It Pa /htdocs
354The file system path to the server document root directory
355relative to the server
356.Xr chroot 2
357directory.
358This is part of the web server configuration and not specific to
359.Nm .
360.It Pa /htdocs/mandoc.css
361A style sheet for
362.Xr mandoc 1
363HTML styling, referenced from each generated HTML page.
364.It Pa /man
365Default
366.Nm
367data directory containing all the manual trees.
368Can be overridden by
369.Dv MAN_DIR .
370.It Pa /man/manpath.conf
371The list of available manpaths, one per line.
372If any of the lines in this file contains a slash
373.Pq Sq /
374or any character not contained in the
375.Sx Restricted character set ,
376.Nm
377reports an internal server error and exits without doing anything.
378.It Pa /man/header.html
379An optional file containing static HTML code to be inserted right
380after opening the <BODY> element.
381.It Pa /man/footer.html
382An optional file containing static HTML code to be inserted right
383before closing the <BODY> element.
384.It Pa /man/OpenBSD-current/man1/mandoc.1
385An example
386.Xr mdoc 7
387source file located below the
388.Dq OpenBSD-current
389manpath.
390.El
391.Sh COMPATIBILITY
392The
393.Nm
394CGI program is call-compatible with queries from the traditional
395.Pa man.cgi
396script by Wolfram Schneider.
397However, the output may not be quite the same.
398.Sh SEE ALSO
399.Xr apropos 1 ,
400.Xr mandoc.db 5 ,
401.Xr makewhatis 8 ,
402.Xr slowcgi 8
403.Sh HISTORY
404A version of
405.Nm
406based on
407.Xr mandoc 1
408first appeared in mdocml-1.12.1 (March 2012).
409The current
410.Xr mandoc.db 5
411database format first appeared in
412.Ox 6.1 .
413.Sh AUTHORS
414.An -nosplit
415The
416.Nm
417program was written by
418.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
419and is maintained by
420.An Ingo Schwarze Aq Mt schwarze@openbsd.org ,
421who also designed and implemented the database format.
422