Annotation of mandoc/man.cgi.8, Revision 1.3
1.3 ! schwarze 1: .\" $Id: man.cgi.8,v 1.2 2014/07/11 21:30:52 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.3 ! schwarze 17: .Dd $Mdocdate: July 11 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
40: A
41: .Dq Search
42: button to send a search request from the client to the server,
43: to be clicked after filling in the following input box(es).
44: .It
45: An input box for search queries, expecting an
46: .Ar expression
47: using the syntax described in the
48: .Xr apropos 1
49: manual; filling this in is required for each search.
50: .It
51: An input box for an optional section number.
52: If one is provided, it has the same effect as the
53: .Xr apropos 1
54: .Fl s
55: option.
56: Otherwise, pages from all sections are shown.
57: .It
58: An input box for an optional architecture name.
59: If one is provided, it has the same effect as the
60: .Xr apropos 1
61: .Fl S
62: option.
63: By default, pages for all architectures are shown.
64: .It
65: A dropdown menu to select a manual tree.
66: If the configuration file
67: .Pa /var/www/man/manpath.conf
68: contains only one manpath, the dropdown menu is not shown.
69: By default, the first manpath given in the file is used.
70: .It
71: A
72: .Dq Reset
73: button to undo any changes to the input boxes and the dropdown menu
74: and reset them to the values contained in the
75: .Ev QUERY_STRING .
76: .El
77: .Ss Program output
78: The
79: .Nm
80: program generates five kinds of output pages:
81: .Bl -tag -width Ds
82: .It The index page.
83: This is returned when calling
84: .Nm
85: without
86: .Ev PATH_INFO
87: and without a
88: .Ev QUERY_STRING .
89: It serves as a starting point for using the program
90: and shows the search form only.
91: .It A list page.
92: Lists are returned when searches match more than one manual page.
93: The first column shows the names and section numbers of manuals
94: as clickable links.
95: The second column shows the one-line descriptions of the manuals.
96: .It A manual page.
97: This output format is used when a search matches exactly one
98: manual page, or when a link on a list page or an
99: .Ic \&Xr
100: link on another manual page is followed.
101: .It A no-result page.
102: This is shown when a search request returns no results -
103: eiher because it violates the query syntax, or because
104: the search does not match any manual pages.
105: .It \&An error page.
106: This cannot happen by merely clicking the
107: .Dq Search
108: button, but only by manually entering an invalid URI.
109: It does not show the search form, but only an error message
110: and a link back to the index page.
111: .El
112: .Ss Setup
113: For each manual tree, create one first-level subdirectory below
114: .Pa /var/www/man .
115: The name of one of these directories is called a
116: .Dq manpath
117: in the context of
118: .Nm .
119: Create a single ASCII text file
120: .Pa /var/www/man/manpath.conf
121: containing the names of these directories, one per line.
122: The directory given first is used as the default manpath.
123: .Pp
124: Inside each of these directories, use the same directory and file
125: structure as found below
126: .Pa /usr/share/man ,
127: that is, second-level subdirectories
128: .Pa /var/www/man/*/man1 , /var/www/man/*/man2
129: etc. containing source
130: .Xr mdoc 7
131: and
132: .Xr man 7
133: manuals with file name extensions matching the section numbers,
134: second-level subdirectories
135: .Pa /var/www/man/*/cat1 , /var/www/man/*/cat2
136: etc. containing preformatted manuals with the file name extension
137: .Sq 0 ,
138: and optional third-level subdirectories for architectures.
139: Use
140: .Xr makewhatis 8
141: to create a
142: .Xr mandoc.db 5
143: database inside each manpath.
144: .Pp
145: Configure your web server to execute CGI programs located in
146: .Pa /cgi-bin .
147: When using
148: .Xr nginx 8 ,
149: the
150: .Xr slowcgi 8
151: proxy daemon is needed to translate FastCGI requests to plain old CGI.
152: .Ss URI interface
153: .Nm
154: uniform resource identifiers are not needed for interactive use,
155: but can be useful for deep linking.
156: They consist of:
157: .Bl -enum
158: .It
159: The
160: .Cm http://
161: protocol specifier.
162: .It
163: The host name and a following slash.
164: .It
165: The path to the program, normally
166: .Pa cgi-bin/man.cgi/ .
167: .It
168: A page name, which can be
169: .Cm index ,
170: which is the default and can be omitted,
171: .Cm search ,
172: or
173: .Cm show .
1.3 ! schwarze 174: .It
1.1 schwarze 175: For
176: .Cm show
177: only, a slash, the manpath, another slash,
178: and the name of the requested file, for example
179: .Pa /OpenBSD-current/man1/mandoc.1 .
180: .It
181: For
182: .Cm search
183: only, a query string starting with a question mark
184: and consisting of
185: .Ar key Ns = Ns Ar value
186: pairs, separated by ampersands, for example
187: .Pa ?manpath=OpenBSD-current&expr=mandoc .
188: Supported keys are
189: .Cm manpath ,
190: .Cm expr ,
191: .Cm sec ,
192: and
193: .Cm arch ,
194: corresponding to
195: .Xr apropos 1
196: .Fl M ,
197: .Ar expression ,
198: .Fl s ,
199: and
200: .Fl S ,
201: respectively.
202: For backward compatibility with the traditional
203: .Nm ,
204: .Cm query
205: is supported as an alias for
206: .Cm expr
207: and
208: .Cm sektion
209: as an alias for
210: .Cm sec .
211: .El
212: .Sh ENVIRONMENT
213: The web server may pass the following CGI variables to
214: .Nm :
215: .Bl -tag -width Ds
216: .It Ev CSS_DIR
217: An optional path to the directory containing the CSS files,
218: to be specified relative to the server's document root,
219: and to be specified without a trailing slash.
220: When not specified, the CSS files
221: are assumed to be in the document root.
222: This is used in generated HTML code.
223: .It Ev HTTP_HOST
224: The FQDN of the (possibly virtual) host the HTTP server is running on.
225: This is used for
226: .Ic Location:
227: headers in HTTP 303 responses.
228: .It Ev MAN_DIR
229: A path to the
230: .Nm
231: data directory to be used instead of
232: .Pa /man ,
233: relative to the web server
234: .Xr chroot 2
235: directory, to be specified without a trailing slash.
236: This is prepended to the manpath when opening
237: .Xr mandoc.db 5
238: and manual page files.
239: .It Ev PATH_INFO
240: The final part of the URI path passed from the client to the server,
241: starting after the
242: .Ev SCRIPT_NAME
243: and ending before the
244: .Ev QUERY_STRING .
245: It is used by the
246: .Cm show
247: page to aquire the manpath and filename it needs.
248: .It Ev QUERY_STRING
249: The HTTP query string passed from the client to the server.
250: It is the final part of the URI, after the question mark.
251: It is used by the
252: .Cm search
253: page to acquire the named parameters it needs.
254: .It Ev SCRIPT_NAME
255: The path to the
256: .Nm
257: binary relative to the server root, usually
258: .Pa /cgi-bin/man.cgi .
259: This is used for generating URIs to be embedded
260: in generated HTML code and HTTP headers.
261: .El
262: .Sh FILES
263: .Bl -tag -width Ds
264: .It Pa /var/www
265: Default web server
266: .Xr chroot 2
267: directory.
268: All the following paths are specified relative to this directory.
269: .It Pa /cgi-bin/man.cgi
270: The path to the
271: .Nm
272: program relative to the server root.
273: Can be overridden by
274: .Ev SCRIPT_NAME .
275: .It Pa /htdocs
276: The path to the server document root relative to the server root.
277: This is part of the web server configuration and not specific to
278: .Nm .
279: .It Pa /htdocs/man-cgi.css
280: A style sheet for general
281: .Nm
282: styling, referenced from each generated HTML page.
283: .It Pa /htdocs/man.css
284: A style sheet for
285: .Xr mandoc 1
286: HTML styling, referenced from each generated HTML page after
287: .Pa man-cgi.css .
288: .It Pa /man
289: Default
290: .Nm
291: data directory containing all the manual trees.
292: Can be overridden by
293: .Ev MAN_DIR .
294: .It Pa /man/manpath.conf
295: The list of available manpaths, one per line.
296: .It Pa /man/OpenBSD-current/man1/mandoc.1
297: An example
298: .Xr mdoc 7
299: source file located below the
300: .Dq OpenBSD-current
301: manpath.
302: .El
303: .Sh COMPATIBILITY
304: The
305: .Nm
306: CGI program is call-compatible with queries from the traditional
307: .Pa man.cgi
308: script by Wolfram Schneider.
309: However, the results may not be quite the same.
310: .Sh SEE ALSO
311: .Xr apropos 1 ,
312: .Xr mandoc.db 5 ,
313: .Xr makewhatis 8 ,
314: .Xr slowcgi 8
1.2 schwarze 315: .Sh HISTORY
316: A version of
317: .Nm
318: based on
319: .Xr mandoc 1
320: first appeared in mdocml-1.12.1 (March 2012).
321: The current SQLite3-based version first appeared in
322: .Ox 5.6 .
1.1 schwarze 323: .Sh AUTHORS
324: .An -nosplit
325: The
326: .Nm
327: program was written by
328: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
329: and ported to the SQLite3-based
330: .Xr mandoc.db 5
331: backend by
332: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb