DemoChoice: Ranked Choice Web Polls
Copyright (C) 2001 Dave Robinson
License information:

This program(*) is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, 
USA.

The license may also be available at:
http://www.gnu.org/copyleft/gpl.html

(*) "This program" refers to software distributed with this document.  The 
original version was made available at:
 http://www.demochoice.org

To clarify, the following are NOT covered by this license:

(1) Graphical logos appearing on the DemoChoice site, and any links or 
scripts related to advertising (Google ads, for example).  If any of these 
were included with the program, this was unintentional.  Links to logos or 
other files not distributed with the program may appear in the program.  
These should be considered bugs and should be deleted before they are used 
to produce web content.

(2) Data files used by the program, and any web content generated by both 
those data files and the program, with the exception of configuration, ballot, 
and tally data files distributed with the program.

(3) Content on the DemoChoice website (http://www.demochoice.org) that 
cannot be generated by the program alone.

(4) Files whose header comments indicate that they are not covered by the 
license or intended for release.

(5) Any section of code between /* NOGPL */ and /* GPL */ comments, which were 
intended to be deleted or modified before release.

(6) The directory buttons, if included, were not created by me and I 
believe they are in the public domain.

Please do not attempt to make a mirror site (one that could be confused 
with the main DemoChoice site, or with a poll hosted by someone else) 
without appropriate permission.  Please try to make your implementation 
unique in some way.

If you will have an introductory page for your poll (similar to the 
DemoChoice main page) and/or a help file (similar to info.php), please 
include a copyright statement in both places, as is done on the DemoChoice 
website.  If you have neither, please display the copyright statement in a 
place that is comparable or similarly accessible to the user.  Including a 
link to the DemoChoice website (assuming it still exists) along with the 
copyright statement would be appreciated.

---

DemoChoice is written mostly in PHP, an open-source, cross-platform scripting 
language (http://www.php.net), and uses no special software components (except 
for pie charts, which use the GD graphics library that is usually, but not 
always, installed with PHP).  You can run DemoChoice on any web server with PHP 
- you can even install a web server like Apache on a laptop and run DemoChoice 
during presentations or conventions.

For improved performance, the main counting engine is in C++.  It's easy to 
compile this (one file, one line) on most machines and a precompiled Windows 
version is available.

Performance boundaries:

It is optimized so that it performs well for large-scale polls (more than
100,000 votes). Note that, for multi-winner elections, it allows for a
small amount of inaccuracy in surplus transfers in order to achieve this
scalability.  Just do a full recount by calling the dccast script with no
form data if you want to see the exact results.

The scalability does not apply when voter registration is used, which is best 
done with less than 1000 voters.

The number of candidates is limited to 255, but this could be expanded without a 
massive effort by changing from char to int in the appropriate parts of the C++ 
source file.  Also, the javascript ballots become slow when the number of 
candidates is huge.  Beyond this, to protect itself against corrupt data files, 
DemoChoice contains an arbitrary file line length limit that limits the number 
of candidates to about 200 in a multi-winner election and 700 in a single-winner 
election.  Changing this limit or the numerical precision can increase this.

DemoChoice is an open-source software package released under the GNU 
General Public License. I hope that this license arrangement will 
encourage development of new features or of other ranked-choice voting 
packages and generally results in widespread use of this election method 
on the web. 

Dave Robinson

Installation issues:

PLEASE DO THIS RIGHT AWAY:
The setup, edit, invite and feedback scripts include an email 
address at the beginning of the file that should be changed to an address 
that you receive.  The feedback script may also contain a link to graphic 
image of an email address that should be modified or deleted.

The server must have write permission on the "data" directory.

The PHP configuration file must set "short_open_tags" to On.  
Alternatively, you can replace all <? tags with <?php in the scripts.

If you want pies to work on a Windows server, get the php_gd2.dll
extension from the PHP package and put it in the directory indicated by
"extension_dir" in the PHP configuration file.  If this value is
undefined, you can put the library in the same directory as the script.  
If the value is defined but you don't have access to the folder, you may
be able to modify the pie.php script with the ini_set() function and get
it to work, but you're on your own in that case.

You can check configuration settings by running a <?php phpinfo(); ?> script.

DemoChoice has been tested on:

Windows 95 / IIS
Windows 2000 / IIS 5.0
Windows 2000 / Apache 1.3 and 2.0
Linux / Apache 2.0
AIX / Apache
Mac OS X (built-in Apache)

using PHP 4.1 and above (including PHP 5).  PHP 5 must be configured to
allow PHP 4's global POST and GET variables.

On many Unix-based systems, including Mac OS X, permissions must be set 
with the chmod command using the operating system's terminal program.  

If your Apache server doesn't recognize index.php as a default page, use a 
non-script default page, or modify the server configuration file in 
/etc/httpd/httpd.conf.  On OS X, only the root user can do this, so it is 
necesary to enable the root user.  See the OS X documentation for details.  
The same is true for the PHP configuration file in 
/usr/bin/php/lib/php.ini.  The OS X "finder" program doesn't normally find 
these files.

If you have successfully installed and tested DemoChoice on a different 
system, please let me know.

If you customize the ballot and place a form before the ballot form, the 
references to document.forms[0] in ballot scripts must be changed to 
document.forms[n] where n is the number of forms preceding the ballot.

You will probably want to update the contact info in the info.php script.

Options:

dcballot.php?terse=on&norot=on

The first parameter shows only the ballot and not the surrounding 
instructions that normally appear.  The second disables the periodic 
shuffling of ballot order, so candidates appear in the order given in the 
ballot file.

dccast.php?terse=on

The option disables the long-winded explanation of one's vote that 
normally appears.

If you call dccast.php with no form data, it will do a full recount (see 
the note about the tally file below if this is the first count).

For invitation-only polls, if you enter the password in the email field on 
the ballot, you can submit a bulk number of votes.  For other polls, the time 
delay between votes can be set to zero in the config file or the password can be 
sent in the URL using &who=[password].

dcresults.php?barmax=500&barht=10&charmax=50&cellpad=3&digits=2

These parameters allow the sizes of the bars in bar charts to be adjusted 
(charmax adjusts the bar size in text-only browsers).  Cellpad refers to the 
spacing in the table form of the results.  Digits is the number of digits after 
the decimal point for numbers reported.

Making a customized poll:

For convenience, you can use the dcsetup.php form, but there are some 
extra features available if you create or edit your poll manually.

Choose a poll name such as "DC" and create the following files:

DC_config.txt  (described below)
DC_tally.txt   (blank)
DC_ballots.txt (blank)

The tally file should contain "Ballots   |1" if you are tallying a new 
ballot file (containing at least one vote) by calling dccast.php with no 
form data.

The config file contains a series of tags:

<TITLE> Who should win the poll?

The title appears at the top of the ballot.

<SEATS> 2

The number of seats to be elected.  Default is 1.

<HARE>

use the Hare quota (votes/seats) instead of Droop (votes/[seats+1])
I think I removed support for this in the summer of 2005.

<NOEX>

Disables the exclusion of exhausted ballots from threshold calculation (for seats > 1)

<DELAY> n

For public polls, impose a delay of n seconds between votes from the same IP 
address.

<UNRECYCLE>

DemoChoice usually recycles ballots to their highest-ranked winner 
if they end up in the exhausted pile in multi-seat elections, but doesn't for 
single-seat elections.  This tag reverses that behavior.

<NODIVS>

Disable the list-sorting feature in touchscreen-style ballots

<INVITE> n

n = number of voters

Voters must enter an email address that is in the DC_registrants.txt file (one 
address per line).  Create a blank DC_voters.txt file too.  Registrants can be 
added during the course of a poll, but n should be updated too.

<USEKEYS>

This tag tells the invite script to look for a registration key rather 
than an email address to use to authenticate voters.

<EXPIRE> n

n = number of seconds between midnight 31 December 1969 and the expiration date.

This only works for <INVITE> polls.  Votes cast after the deadline do not count.
Voters can cast a hypothetical vote after the deadline to see who it would count 
for.

<WITHHOLD>

This only works for <INVITE> polls.  Results are withheld until the poll 
expires.

<CANDIDATE> Fred

List the candidates using these tags, using a separate tag for each candidate.  
Candidate names can contain HTML tags, so you can add pictures or links to 
candidate platforms or websites.  A tag in the form
<a target=_blank href=http://LincolnIn64.com>Abe Lincoln</a>
will create a pop-up that will not reset any existing rankings.

Candidates can be added during the course of the poll, but bad things will 
happen if you delete candidates or change their order.  To remove a candidate, 
use:

<EXCLUDE> x,y,z

where x, y, and z are the numbers of the candidates to be excluded, starting 
with zero, in the order that they appear in the config file.

Several config file tags allow for customization, allowing for adaptation 
to your site or for multiple language support:

<HOMEFILE> myindex.php

sets the 'main page' links that appear in various places.

<INFOFILE> myhelp.php

sets the link to the help file.  Some information is passed in the 
querystring, such as the number of winners and type of ballot used.  This 
can be ignored if you want.

<CASTFILE> mycast.php

sets the form landing page after the ballot is submitted.

<CASTLINK> http://dcballot.php?poll=nextpoll&terse=on

Offers voters a link to another poll after casting a vote.

<RESULTFILE> myresults.php

sets the result page.

<BALLOTFILE> myballot.php

sets the ballot page (I don't think this is used anywhere though)

<BALLOTSTO> MyPoll

Given the label of another poll, all ballots will be written to that poll.  
This allows the results of polls for different languages, precincts, etc. 
to be combined: you would create polls called MyPoll, MyPollSpanish, 
MyPollChinese, etc; the latter two would include the above tag as well as 
BALLOTFILE, CASTFILE, INFOFILE and RESULTFILE tags pointing to files in 
those languages.  It is hoped that files using different languages will 
eventually appear in this distribution.

<INVISIBLE>

This tag is used on the DemoChoice site to prevent polls from being shown 
in the directory.

<EDITPW>

This tag contains a password and email address that can be used to access 
the poll editor script.
