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