SIMPLE VOTING SYSTEM DOCUMENTATION
----------------------------------

Introduction
------------
Simple Voting System, SVS from now on, is a scene party voting system 
originally developed for Vammala party. The application was done as an
exercise task at school by Markku Reunanen (main code & documentation) and
Pablo Virolainen (testing) in 1999. The fellows are known as Marq/Fit and 
Duke NEMO/Coma as well.

SVS consists of configuration files, HTML-files and a couple of CGI-scripts
written in Perl. SVS was designed for and developed under Linux so it should
work straight out-of-the-box on any modern Unix system. Ports to other
systems shouldn't be very difficult either, as long as your OS supports
long filenames and has a HTTP service and Perl interpreter available.

Configuration files
-------------------
The main configuration file is svs.conf located in the main directory.
Currently SVS recognizes the following options:

points:	list	Tells how many points each voted production gets. A simple
		list like 3 2 1 tells the first ranked gets three points etc.
fgcolor: color	Foreground color for SVS's messages and results screen. You
		can use both HTML color names or #RRGGBB hex codes
bgcolor: color	Background color, similarly.
compo: file	Gives a location for a compo file. The compos are enumerated
		in the same order as you specify the compo lines, so when
		you add new compos, add them to the end.

The compo files are simple text files consisting of the compo name on the
first line and the entry names on separate lines. Compo entries are enumerated
in the same order as you specify them, so add new ones to the end to avoid
conflict with the old votes. There is an example svs.conf included plus some
example compo files.

Currently SVS uses the traditional Unix /etc/passwd method for user
authentication (it was easy to code ;v) so whenever you want to give a 
person the possibility to vote, simply create an account for him/her.
Shadow passwords would be nice, but at this point there wasn't enough
time or interest on implementing support for them.

HTML files
----------
The only obligatory HTML file is html/svs.html, which is used as the main page
of the voting. You can make it look like whatever you wish, as long as you
remember the following rules:

- You must have a form similar to this:
  <form action="count.cgi" method="post">
- Your form must have a submit button
  <input type="submit" value="Vote">
- Your form must have a username and a password field:
  <input type="text" name="username">
  <input type="password" name="password">
- Each compo section begins with the tag <!--SVS:COMPO-->
  It initializes the counters and prints the name
- Each place the user can vote has the tag <!--SVS:ENTRIES-->
  It creates a <selection> list of the compo entries eg. if you can vote
  three best entries, make three of these tags.

There is an example of svs.html in the html-directory, it should get you
started.

SVS was designed to give the user control over the visual output if wanted.
Therefore, whenever an error occurs or the voting goes fine, you can have
your own HTML files to give the user a consistent and perhaps even visually
fantastic output. The following files will be shown instead of the usual
messages if found: (they must reside in the html-directory)

svs.ok.html	  The voting went fine
error.auth.html	  Incorrect username or password
error.lock.html	  The votefile is locked
error.config.html Error in SVS configuration
error.file.html	  File error
error.same.html	  Overlapping votes

Perl code
---------
The Perl code in SVS isn't good for your eyes, believe me. However, if you 
intend to change something, here's a brief explanation of the files:

index.cgi	Parses svs.html
count.cgi	Reads data from the form and updates votes
results.cgi	Counts the votes and displays the results
perl/
compo.pl	Reads the compo information files
config.pl	Reads the configuration file
error.pl	Outputs the messages, optionally from HTML
password.pl	Authenticates the voter

File permissions
----------------
Make sure the HTTP service is able to create svs.votes to the main directory
since that's where the votes are stored. Also the HTTP service must be able
to run the CGIs and read every other file. The default user/group for the HTTP 
service on my system is nobody/nobody. Nobody else but the maintainers and
HTTP user should have any access to the voting directory.

Tips
----
- Create a directory called svs.lock to lock the votefile when doing updates
- When adding a new compo on the fly, first create the compo file, then
  add it to svs.conf and finally the HTML tags to avoid conflicts
- If several people are to update the compo files, add them to the HTTP
  user group ('nobody' on my machine) or if you want to restrict their
  access further, create groups and set group permissions on files and
  directories
- Make backup copies of the important files, for example with cron.hourly
- If your Apache setup doesn't seem to run the CGI scripts, check that
  you have the correct permissions in /etc/httpd/conf/access.conf and
  the following enabled in srm.conf:
  AddHandler cgi-script .cgi

Contact information
-------------------
Through e-mail: marq@iki.fi (Markku Reunanen)
WWW page: http://www.iki.fi/marq/svs/
