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

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