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