--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" $Id: sw-cgi.1,v 1.1 1999/07/30 18:46:38 mdw Exp $
+.\"
+.\" 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.
+.
+.\"----- Revision history ---------------------------------------------------
+.\"
+.\" $Log: sw-cgi.1,v $
+.\" Revision 1.1 1999/07/30 18:46:38 mdw
+.\" New CGI script for browsing installed software and documentation.
+.\"
+.
+.\"----- 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 --------------------------------------------------
~mdw / sw-tools / blobdiff