VOTE.PL
	
	Version 2.1.2
	Released 13/07/2002
	
	WWW: http://home.datacomm.ch/atair/perlscript/index.html
	Email: atair@datacomm.ch
	Copyright (c) 2002 A. Schnyder. All Rights Reserved.

##########################################################################
	VOTE.PL README (for version 2.1.2)
##########################################################################

TABLE OF CONTENTS

	 1. Licensing
	 2. Description
	 3. Requirements
	 4. Setup Instructions
	 5. Changing Poll Interface Files
	 6. Changing Poll Result Files
	 7. Logfiles
	 8. Updates History
	 9. Known Issues
	10. Contact and Support Information
	
##########################################################################

1. LICENSING
##########################################################################

	Vote.pl is free software. You can redistribute and modify it 
	freely without any consent of the developer (A. Schnyder), if and 
	only if the following conditions are met:
	
	  (a) The copyright info in the headers remains intact.
	  (b) The purpose of distribution or modification is
	      non commercial.
	      
	Commercial distribution of this product without a written 
	permission from A. Schnyder is strictly prohibited.
	This script is provided without any warranty. The author does not
	take any responsibility for any damage this script may cause.
	
2. DESCRIPTION
##########################################################################

	Vote.pl is a web voting CGI script, that is highly adjustable to 
	your likings. The look of polling interfaces as well as of result 
	pages can be modified by use of html code, to integrate the poll 
	smoothly into the look and feel of your personal site. Vote.pl can
	handle an unlimited number of polls on different pages. IP number 
	tracking and cookies prevent multiple votes from a single user.

	Main Features:
	     * Highly configurable look
	     * View results graphically and/or numerically
	     * User tracking by IP no. and/or cookie prevents multiple 
	       votes.
	     * Provides a maximum number of 23 questions per poll and 999 
	       choices per question
	     * Handles several votings on different pages

3. REQUIREMENTS
##########################################################################
  
	This version of Vote.pl is intended to work with Perl 5. It is 
	assumed that voters use cookie-enabled browsers, otherwise the 
	cookie tracking won't work. When properly installed Vote.pl should 
	run on UNIX and Windows NT/2000. However the author has only 
	tested it on a UNIX system. Of course a cgi-bin directory, a web 
	server, a computer, an internet connection, etc. are required as 
	well. ;-)

4. SETUP INSTRUCTIONS
##########################################################################
	
	Steve Imhof has written a comprehensive guide to Vote.pl. (Thanks 
	fly out to him). If you are unexperienced with CGI, HTML and Perl, 
	I recommend you to read his guide instead of the below 
	instructions, since these are quite short and not intended for 
	newbies. The guide can be found at: 
		
	    http://home.datacomm.ch/atair/perlscript/vote.pl_guide.html

	It follows an instruction how to set up two sample polls, called 
	Example and Test, which come with this script. Afterwards you 
	should be able to adjust these examples to your own polls or 
	questionnaires. 
	
	1. After unzipping vote.zip, you should have the following files:
	
		vote.pl			-	the Vote.pl script
		config.txt		- 	the configurations file
		examp_ip.txt		-	the Example IP logfile
		examp_logfile.txt	-	the Example logfile
		examp_out.html		-	the Example result file
		examp_after.html	-	the Example after voting file
		examp_voted.html	-	the Example already voted
						file
		example.html		-  	the Example interface file
		readme.txt		- 	this file
		test.html		- 	the Test interface file
		test_ip.txt		-	the Test IP logfile
		test_logfile.txt	- 	the Test logfile
		test_out.html		- 	the Test result file
		test_after.html		-	the Test after voting file
		vote.jpg		-	jpg file
		result.jpg		-	jpg file
		black.gif
		blue.gif
		    .
		    .
		yellow.gif		-	gif files

  	2. Make sure the path to the Perl interpreter is correct at the    
	   first line in vote.pl. Initially it is set to
	
			#!/usr/bin/perl
	   
	   If it is different on your server, you need to change it 	
	   accordingly. 	
	   
	3. Open the configurations file 'config.txt' using a text editor.
	
		"***Example***"
		
			This is the name of the first poll (here simply 
			called 'Example'). Needs not to be change. The 
			name of the polls must be between three asterisks. 
		
		"html_file: example.html"
			...
			...
		"already_voted_file: examp_voted.html"
		
			These lines specify the paths to the corresponding
			files. You need not to change these either. 
		
		"vote_url": xxx
		
			Specify the URL for vote.pl. This is the URL you 
			must use to execute the script.
			
		"checkIP": false
			
			Enable or disable IP tracking by setting this flag
			true or false. Initially it is set to false.
		
		"checkCookie": false
		
			Enable or disable cookie tracking. The initial 
			value is false.
			
		"expiration": 200
		
			Specify the cookie expiration time in days. 
			Initially the cookie expires 200 days after it has
			been sent to the user. This means, after 200 days 
			it is possible to vote a second time.
			
		"replace_form_after": true
		
			Enable or disable this feature with 'true' or 
			'false'. If it is enabled, the voting form will 
			be replaced by a results table after casting a 
			vote. Otherwise the results will be displayed on
			a new page.
			
		"replace_form_result": false
		
			Enable or disable this feature with 'true' or 
			'false'. If it is enabled, the voting form will 
			be replaced by a results table when viewing the 
			results. Otherwise the results will be displayed in 
			a blank page.
			
			
		"***Test***"
		
			Name of second poll. (In this case 'Test')
			
		It follows the same configurations for the poll 'Test'. 
		Make same changes as above.
		
		Similarly it would be possible to add a third poll, or 
		even a fourth, fifth, etc.... 
		Simply write the name of a new poll on a new line (between
		three asterisks) and add its configurations underneath. 
			
	 4. Edit interface files using a text editor.
	 	
		Open 'example.html', which belongs to the poll Example.
			
		<form action="xxx" method="get">
			
			Replace "xxx" with the URL for vote.pl. (E.g.: 
			http://mydomain.com/cgi-bin/vote.pl). This is the 
			URL you have specified in Step 3.
				
		<input type="hidden" name="name" value="Example">
			
			This sends the name of the poll (in this case 
			"Example") to vote.pl. Needs not to be changed.
				
		<a href="http://xxx?name=Example&action=view">
			
			Replace "xxx" with the URL for vote.pl. 
				
		Now open 'test.html' and modify it as above.
	 
	 5. Edit result files.
	 
	 	Open 'examp_out.html' and 'test_out.html' and replace all
		'yyy' with the URL of the corresponding pictures.
			
		E.g.:src="yyy/green.gif" -> src="http://mydomain.com/green.gif"
		
		Now do the same with 'examp_after.html' and 'test_after.html'.
	 
	 6. Place following files in your cgi-bin directory with the 
	    corresponding permissions:
		
		file			 permission
		-----------------------------------
		vote.pl				755
		config.txt			644
		examp_ip.txt			666
		examp_logfile.txt		666
		examp_out.html			644
		examp_after.html		644
		examp_voted.html		644
		example.html			644
		test.html			644
		test_ip.txt			666
		test_logfile.txt		666
		test_out.html			644
		test_after.html			644
		
	    Place (a copy) of following files into the public area (that 
	    is, the area that is accessible from typing an URL directly 
	    into a browser)
			
		file			 permission
		-----------------------------------
		example.html			644
		test.html			644
		vote.jpg			644
		result.jpg			644
		black.gif			644
		blue.gif			644
	            .
		    .
		yellow.gif			644
	
	    Note a copy of 'example.html' and 'test.html' must be in the 
	    cgi-bin directory AND in the public area.
	 
	 7. That's it. 
	 	
	    You can access the polls simply by typing the URL of 
	    'example.html' or 'test.html' into a browser.  
       	    To view the poll results use the URL:
		
	      http://www.mydomain.com/cgi-bin/vote.pl?name=nnn&action=view  
	 
5. CHANGING POLL INTERFACE FILES
##########################################################################
	
	When changing interface files you should observe the following 
	rules:
		
	- The maximum number of questions is 23. Per question you can 
	  provide up to 999 answers.
		  
	- Each line ought to contain only one input tag.
		
	- There must be a hidden input tag with name='name' and 	
	  value='name_of_poll'.
		  
	- Questions are labelled using the lowercase alphabet (a to w), 
	  which are in total 23 letters. Provided choices are labelled 
	  using numbers in raising order. 	

6. CHANGING POLL RESULT FILES
##########################################################################

	There are two different files, where you can specify the way the 
	results are displayed. In our Example poll, 'examp_after.html' 
	describes the result page that is shown after a vote is cast. Where
	as 'examp_out.html' defines the page that appears when the 'Result' 
	button is pressed.
	In poll result files you can use the following variables, which 
	will be replaced by the corresponding values, when viewing the 
	results:
	
	- $a1; : no. of votes for the first choice of question 'a'
  	- $%a1;: no. of votes in percent for the first choice of Q 'a'
  	- $a2; : no. of votes for the second choice of Q 'a'
  	- $%a2;: no. of votes in percent for the second choice of Q 'a'
  	- $b1; : no. of votes for the first choice of Q 'b'
	- ...
	- ...
	- etc.
	- $tot;: total votes
		
7. LOGFILES
##########################################################################

	Each voting has its own logfile, where the voting data is saved. 
	If the logfile does not exist the first time vote.pl is executed, 
	it will be created automatically. Every time you add a new 
	question or choice to your poll you have to delete the old 
	logfile, so that vote.pl can create a new logfile, which 
	corresponds to the new questions.
	
	The format of the logfile looks as follows:
		
		Total votes:0
		0 0 0 
		0 0 0 0 0 0
		0 0
		0 0 0

	Each line represents a new question and each column stands for a 
	different choice.
	
8. UPDATES HISTORY
##########################################################################
	
	- Version 2.1.1 released (18/10/2000)
	- Version 2.1.2 released (13/07/2002)
		* Newly added feature: different config-files for 
		  the result file that apears after casting a vote and the
		  file that is shown after pressing the results button.

9. KNOWN ISSUES
##########################################################################

	- User tracking by cookies is not perfect. The user can easily 
	  delete cookie files or disable cookies and vote a second time. 
	  So don't use this feature if your doing anything important, and 
	  cannot simply laugh at those who cheat.

10. CONTACT AND SUPPORT INFORMATION
##########################################################################
	Since Vote.pl is freeware, I do not provide much user support. 
	Please try to find a solution to your problem by yourself by 
	reading the readme.txt very carefully. But if you can't find the 
	answer after doing so , or if you have found a bug, you should 
	contact the developer.

##########################################################################
END OF README.TXT