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