| 1 | .\" -*-nroff-*- |
| 2 | .\" |
| 3 | .\" $Id$ |
| 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 | .\"----- 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 | |
| 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 -------------------------------------------------- |