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