.\" -*-nroff-*-
.\"
.\" $Id$
.\"
.\" Man page for `sw' CGI script
.\"
.\" (c) 1999 EBI
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of sw-tools.
.\"
.\" sw-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\" 
.\" sw-tools is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with sw-tools; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"----- Style hacking ------------------------------------------------------
.
.de VS \" Start a sort-of verbatim block
.sp 1
.in +5n
.nf
.ft B
..
.de VE \" Stop a sort-of verbatim block
.ft R
.fi
.in -5n
.sp 1
..
.ie \n(.g \{\
. fam P
. ds mw \fR[\f(BImdw\fR]
.\}
.el .ds mw \fR[\fBmdw\fR]
.ie t .ds o \(bu
.el .ds o o
.ds sw \fBsw\fP
.
.\"----- Main manual text ---------------------------------------------------
.
.TH sw-cgi 1 "30 July 1999" sw-tools
.PD 1
.
.\"--------------------------------------------------------------------------
.
.SH "NAME"
.
sw-cgi \- CGI script for browsing installed software and documentation
.
.\"--------------------------------------------------------------------------
.
.SH "SYNOPSIS"
.
.IB prefix /cgi-bin/sw
.RI [ key = value ]...
.
.\"--------------------------------------------------------------------------
.
.SH "DESCRIPTION"
.
The
.B sw
CGI script provides users with a pleasant-ish interface for browsing the
list of locally installed software and its documentation.
.PP
The script picks up arguments from HTTP
.B GET
or
.B POST
requests, or from the command line (which is useful when debugging).
Given no arguments, it emits a table of installed software read from the
index file in
.IB prefix /sw-index
together with links to documentation.
.PP
The program assumes that any
.I package
has documentation stashed in
.IB prefix /doc/ package
in plain text format.  You can require your installers to do this by
putting this code in a
.B sw-precommit
script (see the
.B "Command reference"
in
.BR sw (1)
for details):
.VS
# --- Ensure the documentation file exists ---

if [ ! -r "$SW_PREFIX/doc/$SW_PACKAGE" ]; then
  echo >&2 "no documentation file \`$SW_PREFIX/doc/$SW_PACKAGE'"
  exit 1
fi
.VE
Links to these documentation files are put into the table
automatically.  The script picks out likely-looking references to other
sources of information:
.TP
.I "manual pages"
A reference of the form
.IB name ( section )
is suspected of being a manual page; the script looks in the manual
directories to see if this is the case and if so inserts a hypertext
link to the manual page.  This is the standard form for manual page
references.
.TP
.I "info manuals"
A reference of the form
.BI info: name
is assumed to be a reference to the GNU Info manual called
.I name
and an appropriate link inserted.  There isn't a standard form for Info
references in non-Info manuals, so I've invented one.
.TP
.I "URLs"
A URL which begins with one of
.B http://
or
.B ftp://
is spotted and turned into a link.  Only these two work.
.TP
.I "email addresses"
Something that looks like an email address is turned into a
.B mailto
link.
.PP
Similar transformations are applied to manual pages when they're
formatted.
.
.SS "Script arguments"
The behaviour of the script is determined by the value of the
.B act
key.  Any of the following may be given:
.TP
.B list
Emit the list of packages in tabular form.  This is the default if no
.B act
is given.
.TP
.B doc
Format a textual documentation file.  The name of the package whose
documentation is to be emitted is given as the value of the
.B pkg
key.
.TP
.B man
Format a manual page, or emit a manual index.  If no
.B sec
key is given, an index of all manual pages in the software area is
produced.  If
.B sec
is a manual page section (e.g.,
.BR 1 ,
not
.BR man1 )
but
.B man
is not given then an index of that particular section is emitted.  If
both
.B sec
and
.B man
are supplied then the manual page whose name is given by the
.B man
key in the section given by the
.B sec
key is formatted (using
.BR nroff (1))
and displayed.  Manual page references, URLs and email addresses are
transformed into links in the output.
.TP
.B info
Format a GNU Info node.  If the
.B file
key is given, its value names an Info manual to open; the default is
.BR dir .
If the
.B node
key is given, its value names a node within the manual; the default is
.BR Top .
.TP
.B show-config
Emits a table showing the configuration settings which the script is
aware of.  See
.B Configuration
below.  This is useful during debugging.
.TP
.B show-environment
Displays the environment variables passed to the script by the Web
server.  This is useful during debugging.
.TP
.B show-query
Displays the query string passed by the Web server, decomposed into keys
and values and decoded.  This is useful during debugging.
.
.SS "Configuration"
The
.B sw
CGI script needs some configuration before it can do its work properly.
Indeed, it will refuse to run until the configuration file has been
edited.
.PP
The configuration file is in
.IB prefix /share/sw.conf\fR.
The format is simple.  A line may be empty, or a comment, in which case
it is ignored.  Comments have 
.RB ` # '
as their first non-whitespace character; blank lines contain only
whitespace.  A line may also contain a configuration variable
assignment, of the form
.I key
.RB  [ = ]
.IR value .
The
.I key
may be anything you like; only certain keys make sense to the script.
.PP
Configuration keys currently used are:
.TP
.B pkg
The name of the package in which the script came.  This is set
automatically and you should not change the value.
.TP
.B version
The version number of the package.  This is set automatically and you
should not change the value.
.TP
.B edited-config-file
Must be assigned the value
.BR yes .
If this is not the case the script will immediately report an error.
The default configuration file comes with a commented-out assignment to
this variable.
.TP
.B prefix
The installation prefix where your software gets installed.  You
shouldn't need to change this, although it's handy for debugging.
.TP
.BR index ", " doc " and " datadir
The name of the index file, documentation directory and shared data
directory respectively.  The default values of these variables are set
automatically and you shouldn't need to change them.
.TP
.B domain
Your email domain.  Set this to the domain part for email addresses of
people at your site, and the script will generate correct links in its
main list page.
.
.\"--------------------------------------------------------------------------
.
.SH "SEE ALSO"
.BR sw (1),
.BR sw-info (5).
.
.SH "AUTHOR"
.
The \*(sw program, and this manual, are \*(mw productions, in association
with the European Bioinformatics Institute.  They were written by Mark
Wooding <mdw@nsict.org>.  Go and ask him if you have problems.
.
.\"----- That's all, folks --------------------------------------------------