Overview
========
Parses XML notices sent via email by the GCN (http://gcn.gsfc.nasa.gov)
creates a sqlite database with a subset of the data sent and calculates the
zenith angle of the GCN.

Included files:
===============
* README : this file
* gcn_parser.py : File which is run upon the arrival of an email
* gcn_dbinterface.py : Module which defines the database structure
* bitly.py : Shortens URLs using bit.ly
* sql_interface.py : Basic interface to sqlite
* site-alerter.py : Builds an XML file and images for each GCN
* site-alerter-daemon.py : Runs site-alerter periodically.

Environment
===========
Required python modules:
------------------------
### bitly ###
* urllib2 [for shortening not required]
### sql_interface ###
* sqlite3 [falls back to sqlite]
### gcn_dbinterface ###
* sql_interface [above]
### gcn-parser ###
* gcn_dbinterface [above]
* xml.etree.ElementTree or elementtree.ElementTree'
### site-alerter ###
* gcn_dbinterface [above]
* xml.etree.ElementTree or elementtree.ElementTree'
* numpy
* smtplib
* email
* matplotlib
* ephem
* bitly [above]
### site-alerter-daemon ###
* daemon

Expected environmental variables:
---------------------------------
* HOME : home directory used to set defaults for missing environmental variables
### bitly ###
* BITLYAPI : Points to file with two lines: bitly username and bitly API key
             Default: ${HOME}/.bitlyapi
### gcn-parser ###
* GCNDB : Location of sqlite GCNs data base file
          Default: $GCNWEB/gcns.db
* GCNDBNAME : Name of data base within $GCNDB used to store GCNs
              Default: gcns
* GCNLOG : Log file used
           Default: $HOME/logs/gcn-parser.log
* GCNALERTS : If set then gcn-parser will call site-alerter
              Default: unset
### site-alerter ###
* GCNDB : Location of sqlite GCNs data base file
          Default: $HOME/gcns.db
* GCNDBNAME : Name of data base within $GCNDB used to store GCNs
              Default: gcns
* SALERTDB : Location of sqlite alerts data base file
          Default: $HOME/alerts.db
* SALERTDBNAME : Name of data base within $SALERTDB used to store alerts
              Default: alerts
* SALERTCFG : Configuration file for sending site alerts
              Default: None
* SALERTLOG : Log file used
              Default: $HOME/logs/site-alerter.log
* GCNSITE : Tag used to denote the site
            Default: HAWC
* GCNSITELAT : Latitude in degrees North for site
               Default: +19.0304954539937
* GCNSITELONG : Longitude in degrees East for site
                Default: -97.2698484177274
* GCNSITEHORIZON : Altitude angle in degrees to consider rising and setting
                   Default: 45.0
* GCNHTTP : HTTP base for site being generated
            REQUIRED
* GCNSMTP : SMTP server from which to send email alerts
            REQUIRED
* GCNWEB : Base directory to output web page related files
           Default: $HOME/public_html
* GCNSITELINK : Link to site constructed by site-alerter
                Default: $GCNHTTP
* NOUTGCNS : Number of GCNs to output to web page
             Default: 100
### site-alerter-daemon ###
* GCNDAEMONLOG : Log file used
                 Default: $HOME/logs/gcn-daemon.log
* GCNDAEMONLOCK : Lock file used
                 Default: /tmp/site-alerter-daemon.lock
* GCNDBSRV : Server from which to obtain GCNDB and to push generated content
              REQUIRED
* GCNDBOSRV : Location of GCNDB on server
              REQUIRED
* GCNWEBOSRV : Base directory to output web content (on server)
               Default: $HOME/public_html
* GCNWEB : Base directory to output web content (locally)
           Default: $HOME/public_html
* GCNINTER : Seconds between updates
             Default: 60

USAGE
=====
Ideally one should pass the contents of an email to this gcn-parser via
procmail. It will read the data from stdin and process it.

site-alerter, if able, should be run from gcn-parser by setting GCNALERTS. If
site-alerter cannot run on the same machine as gcn-parser then
site-alerter-daemon can be used to query the machine running gcn-parser.

site-alerter-daemon assumes that the