Simple Voting Program
---------------------

This simple voting program consists of several perl scripts hacked
together by Chuck (chuck@ccrc.wustl.edu) and Lorrie (lorracks@cs.wustl.edu)
Cranor for a graduate student government election.  If you find it useful, 
feel free to use it.  Beware that this software is not designed for 
applications that require much in the way of security.  Use at
your own risk. 


To run an election using this simple voting program you must
have the following files in a directory XXX, where XXX is a label
for the particular election you are currently running:  

options  -  A list of vote choices, each on a separate line.

already  -  an empty file

In addition, you must also have the following files in XXX.
You can name these files whatever you want -- the following file 
names are used to make these instructions easy to understand:

LIST  -  The list of voters' email addresses.  Each address should
         be on a separate line.

MESSAGE  -   The voting instructions.  This file should be a letter
             to voters explaining how to vote. 

REMIND-MESSAGE  -  The reminder letter (optional).   This file should
                   be a letter reminding voters to vote.  It should
                   repeat the instructions given in MESSAGE.


Once you have prepared these files, follow these steps:

1. Create a .maildelivery file in your home directory that contains
   the following lines:

   addr    REPLY-TO       pipe    R    /usa/vote/bin/parse /usa/vote/XXX
   addr    REPLY-TO       file    A    /usa/vote/XXX/ballots

   (REPLY-TO should be the reply-to address, vote=XXX@maria.wustl.edu)

2. After CDing to XXX, generate a random ID number for each email address 
   in LIST by running:

   list2rndlist LIST > randlist 

3. Send voting instructions to each email address in LIST by running:

   rndl2mail MESSAGE randlist

   You will be prompted to enter information for the subject, from,
   and reply-to lines.   Make sure to enter REPLY-TO for the reply-to line. 

4. (optional)  After sufficient time has passed, remind voters who
   have not yet voted to vote.  First generate a list of voters
   who have not voted by running:

   remind randlist already > REMINDLIST

   Then send the reminder by running:

   rndl2mail REMIND-MESSAGE REMINDLIST

   Once again you will be prompted for the subject, from, and
   reply-to lines.  Make sure you use the same reply-to line as
   used above.

5. When the vote casting period is over, if all went well you should
   have a file for each vote choice in the XXX directory.  In an
   election with vote choices a, b, and c, you should have files
   vote.a, vote.b, and vote.c in the XXX directory.  In addition
   you should have a file called 'already' that contains
   a list of ballot IDs for the counted ballots, and a file
   called 'ballots' that contains all ballots received, including
   the ones not counted.  To verify that each voter really only 
   voted once (or if a voter voted more than once, only one of
   his or her ballots was counted), run:

   verify vote.*

   If verify finds problems, you will have to track them down
   manually by inspecting the ballots file.  Even if verify
   does not detect a problem, you might want to inspect
   ballots to make sure that there aren't lots of ballots
   that didn't get parsed.

6. Count the votes by running:

   wc vote.*