961ce1c2 |
1 | .\" -*-nroff-*- |
2 | .\" |
3 | .\" $Id: sw-cgi.1,v 1.1 1999/07/30 18:46:38 mdw Exp $ |
4 | .\" |
5 | .\" Man page for `sw' CGI script |
6 | .\" |
7 | .\" (c) 1999 EBI |
8 | .\" |
9 | . |
10 | .\"----- Licensing notice --------------------------------------------------- |
11 | .\" |
12 | .\" This file is part of sw-tools. |
13 | .\" |
14 | .\" sw-tools is free software; you can redistribute it and/or modify |
15 | .\" it under the terms of the GNU General Public License as published by |
16 | .\" the Free Software Foundation; either version 2 of the License, or |
17 | .\" (at your option) any later version. |
18 | .\" |
19 | .\" sw-tools is distributed in the hope that it will be useful, |
20 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
21 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
22 | .\" GNU General Public License for more details. |
23 | .\" |
24 | .\" You should have received a copy of the GNU General Public License |
25 | .\" along with sw-tools; if not, write to the Free Software Foundation, |
26 | .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
27 | . |
28 | .\"----- Revision history --------------------------------------------------- |
29 | .\" |
30 | .\" $Log: sw-cgi.1,v $ |
31 | .\" Revision 1.1 1999/07/30 18:46:38 mdw |
32 | .\" New CGI script for browsing installed software and documentation. |
33 | .\" |
34 | . |
35 | .\"----- Style hacking ------------------------------------------------------ |
36 | . |
37 | .de VS \" Start a sort-of verbatim block |
38 | .sp 1 |
39 | .in +5n |
40 | .nf |
41 | .ft B |
42 | .. |
43 | .de VE \" Stop a sort-of verbatim block |
44 | .ft R |
45 | .fi |
46 | .in -5n |
47 | .sp 1 |
48 | .. |
49 | .ie \n(.g \{\ |
50 | . fam P |
51 | . ds mw \fR[\f(BImdw\fR] |
52 | .\} |
53 | .el .ds mw \fR[\fBmdw\fR] |
54 | .ie t .ds o \(bu |
55 | .el .ds o o |
56 | .ds sw \fBsw\fP |
57 | . |
58 | .\"----- Main manual text --------------------------------------------------- |
59 | . |
60 | .TH sw-cgi 1 "30 July 1999" sw-tools |
61 | .PD 1 |
62 | . |
63 | .\"-------------------------------------------------------------------------- |
64 | . |
65 | .SH "NAME" |
66 | . |
67 | sw-cgi \- CGI script for browsing installed software and documentation |
68 | . |
69 | .\"-------------------------------------------------------------------------- |
70 | . |
71 | .SH "SYNOPSIS" |
72 | . |
73 | .IB prefix /cgi-bin/sw |
74 | .RI [ key = value ]... |
75 | . |
76 | .\"-------------------------------------------------------------------------- |
77 | . |
78 | .SH "DESCRIPTION" |
79 | . |
80 | The |
81 | .B sw |
82 | CGI script provides users with a pleasant-ish interface for browsing the |
83 | list of locally installed software and its documentation. |
84 | .PP |
85 | The script picks up arguments from HTTP |
86 | .B GET |
87 | or |
88 | .B POST |
89 | requests, or from the command line (which is useful when debugging). |
90 | Given no arguments, it emits a table of installed software read from the |
91 | index file in |
92 | .IB prefix /sw-index |
93 | together with links to documentation. |
94 | .PP |
95 | The program assumes that any |
96 | .I package |
97 | has documentation stashed in |
98 | .IB prefix /doc/ package |
99 | in plain text format. You can require your installers to do this by |
100 | putting this code in a |
101 | .B sw-precommit |
102 | script (see the |
103 | .B "Command reference" |
104 | in |
105 | .BR sw (1) |
106 | for details): |
107 | .VS |
108 | # --- Ensure the documentation file exists --- |
109 | |
110 | if [ ! -r "$SW_PREFIX/doc/$SW_PACKAGE" ]; then |
111 | echo >&2 "no documentation file \`$SW_PREFIX/doc/$SW_PACKAGE'" |
112 | exit 1 |
113 | fi |
114 | .VE |
115 | Links to these documentation files are put into the table |
116 | automatically. The script picks out likely-looking references to other |
117 | sources of information: |
118 | .TP |
119 | .I "manual pages" |
120 | A reference of the form |
121 | .IB name ( section ) |
122 | is suspected of being a manual page; the script looks in the manual |
123 | directories to see if this is the case and if so inserts a hypertext |
124 | link to the manual page. This is the standard form for manual page |
125 | references. |
126 | .TP |
127 | .I "info manuals" |
128 | A reference of the form |
129 | .BI info: name |
130 | is assumed to be a reference to the GNU Info manual called |
131 | .I name |
132 | and an appropriate link inserted. There isn't a standard form for Info |
133 | references in non-Info manuals, so I've invented one. |
134 | .TP |
135 | .I "URLs" |
136 | A URL which begins with one of |
137 | .B http:// |
138 | or |
139 | .B ftp:// |
140 | is spotted and turned into a link. Only these two work. |
141 | .TP |
142 | .I "email addresses" |
143 | Something that looks like an email address is turned into a |
144 | .B mailto |
145 | link. |
146 | .PP |
147 | Similar transformations are applied to manual pages when they're |
148 | formatted. |
149 | . |
150 | .SS "Script arguments" |
151 | The behaviour of the script is determined by the value of the |
152 | .B act |
153 | key. Any of the following may be given: |
154 | .TP |
155 | .B list |
156 | Emit the list of packages in tabular form. This is the default if no |
157 | .B act |
158 | is given. |
159 | .TP |
160 | .B doc |
161 | Format a textual documentation file. The name of the package whose |
162 | documentation is to be emitted is given as the value of the |
163 | .B pkg |
164 | key. |
165 | .TP |
166 | .B man |
167 | Format a manual page, or emit a manual index. If no |
168 | .B sec |
169 | key is given, an index of all manual pages in the software area is |
170 | produced. If |
171 | .B sec |
172 | is a manual page section (e.g., |
173 | .BR 1 , |
174 | not |
175 | .BR man1 ) |
176 | but |
177 | .B man |
178 | is not given then an index of that particular section is emitted. If |
179 | both |
180 | .B sec |
181 | and |
182 | .B man |
183 | are supplied then the manual page whose name is given by the |
184 | .B man |
185 | key in the section given by the |
186 | .B sec |
187 | key is formatted (using |
188 | .BR nroff (1)) |
189 | and displayed. Manual page references, URLs and email addresses are |
190 | transformed into links in the output. |
191 | .TP |
192 | .B info |
193 | Format a GNU Info node. If the |
194 | .B file |
195 | key is given, its value names an Info manual to open; the default is |
196 | .BR dir . |
197 | If the |
198 | .B node |
199 | key is given, its value names a node within the manual; the default is |
200 | .BR Top . |
201 | .TP |
202 | .B show-config |
203 | Emits a table showing the configuration settings which the script is |
204 | aware of. See |
205 | .B Configuration |
206 | below. This is useful during debugging. |
207 | .TP |
208 | .B show-environment |
209 | Displays the environment variables passed to the script by the Web |
210 | server. This is useful during debugging. |
211 | .TP |
212 | .B show-query |
213 | Displays the query string passed by the Web server, decomposed into keys |
214 | and values and decoded. This is useful during debugging. |
215 | . |
216 | .SS "Configuration" |
217 | The |
218 | .B sw |
219 | CGI script needs some configuration before it can do its work properly. |
220 | Indeed, it will refuse to run until the configuration file has been |
221 | edited. |
222 | .PP |
223 | The configuration file is in |
224 | .IB prefix /share/sw.conf\fR. |
225 | The format is simple. A line may be empty, or a comment, in which case |
226 | it is ignored. Comments have |
227 | .RB ` # ' |
228 | as their first non-whitespace character; blank lines contain only |
229 | whitespace. A line may also contain a configuration variable |
230 | assignment, of the form |
231 | .I key |
232 | .RB [ = ] |
233 | .IR value . |
234 | The |
235 | .I key |
236 | may be anything you like; only certain keys make sense to the script. |
237 | .PP |
238 | Configuration keys currently used are: |
239 | .TP |
240 | .B pkg |
241 | The name of the package in which the script came. This is set |
242 | automatically and you should not change the value. |
243 | .TP |
244 | .B version |
245 | The version number of the package. This is set automatically and you |
246 | should not change the value. |
247 | .TP |
248 | .B edited-config-file |
249 | Must be assigned the value |
250 | .BR yes . |
251 | If this is not the case the script will immediately report an error. |
252 | The default configuration file comes with a commented-out assignment to |
253 | this variable. |
254 | .TP |
255 | .B prefix |
256 | The installation prefix where your software gets installed. You |
257 | shouldn't need to change this, although it's handy for debugging. |
258 | .TP |
259 | .BR index ", " doc " and " datadir |
260 | The name of the index file, documentation directory and shared data |
261 | directory respectively. The default values of these variables are set |
262 | automatically and you shouldn't need to change them. |
263 | .TP |
264 | .B domain |
265 | Your email domain. Set this to the domain part for email addresses of |
266 | people at your site, and the script will generate correct links in its |
267 | main list page. |
268 | . |
269 | .\"-------------------------------------------------------------------------- |
270 | . |
271 | .SH "SEE ALSO" |
272 | .BR sw (1), |
273 | .BR sw-info (5). |
274 | . |
275 | .SH "AUTHOR" |
276 | . |
277 | The \*(sw program, and this manual, are \*(mw productions, in association |
278 | with the European Bioinformatics Institute. They were written by Mark |
279 | Wooding <mdw@nsict.org>. Go and ask him if you have problems. |
280 | . |
281 | .\"----- That's all, folks -------------------------------------------------- |