mdw@git.distorted.org.uk Git - sw-tools/blob - perl/sw-cgi.1

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