| 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 -------------------------------------------------- |