SoftDB -- Software Database Documentation
--------------------------------------------------------------
Author: John E. Stone 
  Theoretical Biophysics Group
  NIH Resource for Macromolecular Modeling and Bioinformatics
  Copyright 2001 Board of Trustees of the University of Illinois


Introduction
------------
  This small set of scripts, and HTML files constitute a mechanism
for implementing a Web-interfaced database of software packages.  
It was conceived as a tool that would be useful for researchers in
structural biology looking for programs to help them with their
computer simulations.  One of the problems in this field is
that there are hundreds, if not thousands, of computer programs
which have been developed over the years for various purposes, and
although there are many lists of these packages on the web, most
are simply raw lists written in HTML by hand, which have very brief
descriptions of what the programs do.  Many of these existing lists
are not searchable in a useful way, and cannot be easily added to
using a nice submission mechanism.  This database was intended to 
provide a list of useful software, much like the others on the 
internet, but would be searchable, easy to add to and administrate,
and would be open-source so that others could use the same package 
for their own lists of software.    


Why use Perl???
---------------
  Some people may be curious why Perl was chosen to implement this
system.  The reasons are actually quite simple.  A scripting language
is the ideal way to implement a system like this when it is in an 
early stage of development, and performance is not critical.  Developing
using an interpreted language allows one to go through many debug/test/change
cycles very rapidly, without having to recompile.  In addition to the 
interpreted language feature, Perl also implements a good database 
interface known as "DBI", which was instrumental in getting a prototype
implementation of the software database going very rapidly.


Customization for New Sites, New Databases
------------------------------------------
  Several of the scripts in this system currently require modification
in order to work at another site, or for another database.  This is a 
shortcoming of the current design of the package, but may be improved
dramatically with future versions.  Most of these modifications are
unavoidable such as rewriting the index.html page for the new site, 
new database, and appropriate contents.  The remainder of the 
modifications relate to changing email addresses in the script,
database name, host, and passwords, etc.  In order to make these 
modifications, a user must be familiar with Perl, CGI, DBI, and
potentially SQL.  Fear not however, it is pretty easy to get the
software running, its just that these little details are what
give your database its personality, so its worth spending a few
minutes on it.


Manifest of files
-----------------
addrecords.pl      - Hard-coded script to add new categories and applications
                     to the DB.  Useful for testing/demonstration only.
                     Needs to be modified for each new site/DB, if used.
                     Requires Perl DBI module.

appaddrequest.html - HTML web page implementing a submission form for
                     new software packages users would like added to the DB.
                     Needs to be modified for each new site/DB.

appaddrequest.cgi  - Back-end CGI script which converts submitted form
                     data into an email message which is sent to the
                     DB maintainers.  Depends on cgi-lib.pl 
                     Needs to be modified for each new site/DB.

biosoft.cgi        - Main CGI script implementing DB interface.
                     Shouldn't need to be modified normally.
                     Requires Perl CGI and DBI modules.

dbconfig.pl        - Main SoftDB configuration file, contains hostnames,
                     passwords, and web formatting customization routines
                     that you need to modify for your site when you 
                     first create the database.  As the software improves,
                     even more of the look and feel of the database will
                     be configurable from this file, and there will be no
                     need to modify any of the other scripts under normal
                     circumstances.

index.html         - Main web page for the database, usually contains
                     usage info, announcements, links to related stuff.

makedb.pl          - Script to drop/recreate/create the database and
                     add its tables and basic structure.  Needs to be run
                     several times when DB is first being setup/tested 
                     before real data as actually entered while testing.
                     Never used again on real DB once DB is in production.
                     Shouldn't need to be modified normally.
                     Requires Perl DBI module.


admin/ - subdirectory containing administrative files
 
    editbiosoft.cgi - Main editing interface, shouldn't need to be modified
                      normally.
                      Requires Perl CGI and DBI modules.

    .htaccess       - used to limit who can access the administrative
                      functions of the database, consult your local web
                      administrator for more information.  This file limits
                      access to the editing CGI.