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