Work around CloneProofSSD returning [nil] rather than [] for empty vote

[rubyvote] / README

diff --git a/README b/README
index 7029d84601874efa1fe66198692f9015a5688eed..efd0ddfff5d9f6098fea1f858ab5e56883ffb27f 100644 (file)
--- a/README
+++ b/README
@@ -1,43 +1,76 @@
 RubyVote: Election Methods Library in Ruby
 RubyVote: Election Methods Library in Ruby

-===========================================
+=============================================

 
 

-:Author: Benjamin Mako Hill
-:Copyright: MIT Media Lab and MIT
-:License: GNU GPL
+.. Caution::

 
 

-Summary
---------
+   This software is pre release software. The authors of this software
+   are neither expert Ruby programmers or elections in election
+   methods. We are hackers and enthusiasts in both. This software has
+   bugs and it's quite possible that is has bugs that may skew
+   results. If you understand Ruby or election methods, please audit
+   the code.
+
+Overview
+---------
+
+**Latest Version:** 0.2
+
+**Download Latest Version:** `here
+<http://rubyforge.org/projects/rubyvote>`__
+
+`RubyVote` is an election methods library implemented in Ruby.  It is
+designed to make it very easy to implement a variety of different types
+of elections in Ruby including relatively complex election methods like
+Condorcet.  It could be useful for any sort of election, poll, or
+decision making.
+
+New Versions
+*************
+
+`RubyVote` is graciously hosted by `RubyForge
+<http://rubyforge.org/>`__.
+
+You can visit the `RubyVote` homepage (a version of this file) here:
+
+ http://rubyvote.rubyforge.org/

 
 

-**Version:** 0.1
+You can visit the RubyForge project page to download the latest
+version of software, get access to the latest development version from
+Subversion, to file or bug, to look through documentation, to
+participate in the forums, or to contribute in other ways. That page
+is here:

 
 

-This software includes an set of classes to tally votes and compute
-winners in elections or votes using a series of different
-methods. Currrently these include:
+ http://rubyforge.org/projects/rubyvote

 
 

-* Plurality or "winner-take-all"
-* Approval
-* Borda
-* Simple Condorcet
-* Condorcet with Cloneproof SSD

 
 

-More information can be found at the following pages:
+More Information
+*****************

 
 

-* http://en.wikipedia.org/wiki/Plurality_electoral_system
-* http://en.wikipedia.org/wiki/Approval_voting
-* http://en.wikipedia.org/wiki/Borda_count
-* http://en.wikipedia.org/wiki/Condorcet_method
-* http://en.wikipedia.org/wiki/Shulze_method
+`RubyVote` is a library -- not an application or a voting machine. It
+simply takes the raw "tallies" of votes and computes the results.
+Currently, it does not include any sample interfaces (although if
+contributed, these may be included).

 
 

-Writing support for a new module (e.g., instant runnof voting) is a
-fantastic way to to contribute to this module.
+`RubyVote` current includes a set of classes to tally votes and compute
+winners in elections or votes using a series of different methods.
+Currently these include:

 
 

-This software is prerelease software. I am both a relatively new Ruby
-progreammming and relatively new to election methods. These election
-methods have bugs and may have bugs that skew results. If you are
-understand Ruby and election methods, please do me a favor and audit
-my code.
+* `Plurality`__ or "winner-take-all"
+* `Approval`__
+* `Borda`__
+* `Simple Condorcet`__
+* `Condorcet with Cloneproof SSD`__
+* `Instant Runnoff Voting`__ (Thanks Alexis Darrasse!)

 
 

+__ http://en.wikipedia.org/wiki/Plurality_electoral_system
+__ http://en.wikipedia.org/wiki/Approval_voting
+__ http://en.wikipedia.org/wiki/Borda_count
+__ http://en.wikipedia.org/wiki/Condorcet_method
+__ http://en.wikipedia.org/wiki/Schulze_method
+__ http://en.wikipedia.org/wiki/Instant_Runoff_Voting

 
 

+Writing support for a currently unsupported voting method is a fantastic
+way to to contribute to this module.

 
 How To Use This Library
 -------------------------
 
 How To Use This Library
 -------------------------


@@ -49,15 +82,16 @@ new vote object. You should then either pass an array of votes to the
 object upon creation or pass votes in one at at a time.
 
 
 object upon creation or pass votes in one at at a time.
 
 

-.. Note:: *You* are responsible for ensuring that the votes are in
-         correct form before you hand them to this module. This will
-         not currently check for most types of invalid votes and does
-         not (currently) accept a list of candidates at creation from
-         which it checks all votes. As such, new candidates will be
-         created when seen. If you think this is a meaningful
-         addition to this library, please send a patch. Otherwise,
-         please check for the validity of votes BEFORE you pass them
-         to this election module.
+.. Note::
+
+   *You* are responsible for ensuring that the votes are in correct
+   form before you hand them to this module. This will not currently
+   check for most types of invalid votes and does not (currently)
+   accept a list of candidates at creation from which it checks all
+   votes. As such, new candidates will be created when seen. If you
+   think this is a meaningful addition to this library, please send a
+   patch. Otherwise, please check for the validity of votes BEFORE you
+   pass them to this election module.

 
 Examples of each type of election currently supported can be seen in
 the test.rb file distributed in this archive.
 
 Examples of each type of election currently supported can be seen in
 the test.rb file distributed in this archive.


@@ -147,12 +181,29 @@ Example::
  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
  resultobject = CloneproofSSDVote.new(vote_array).result
 
  vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
  resultobject = CloneproofSSDVote.new(vote_array).result
 

+Instant Runnoff Voting (IRV)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+IRV is a preferential voting system used widely for government elections
+in Australia and New Zealand and elsewhere. IRV asks voters to rank
+candidates in preference and then holds a series of "runoff" elections
+by eliminating the weakest candidate and recomputing the election
+results until there exists a candidate who has a majority of the
+remaining votes.
+
+Example::
+
+ require 'runoff'
+ vote_array = [ ["A", "B"],  ["B", "A"], ["B", "A"] ]
+ resultobject = InstantRunoffVote.new(vote_array).result
+
+

 ElectionResult Objects
 ***********************
 
 Each election result object will have the following methods:
 
 ElectionResult Objects
 ***********************
 
 Each election result object will have the following methods:
 

-* #winner? -- return boolean as to the winner or winners of an election
+* #winner? -- return Boolean as to the winner or winners of an election

 * #winners -- an array of winners of the election
 * #ranked_candidates -- (where available) a list of ranked candidates
 
 * #winners -- an array of winners of the election
 * #ranked_candidates -- (where available) a list of ranked candidates
 


@@ -184,7 +235,7 @@ Currently, the only contributor to this program is Benjamin Mako Hill
 working at the MIT Media Lab. Please feel free to contribute to this
 module and get your name added here.
 
 working at the MIT Media Lab. Please feel free to contribute to this
 module and get your name added here.
 

-For more information about Mako and his programs, you can seee his
+For more information about Mako and his programs, you can see his

 homepage here:
 
  http://mako.cc
 homepage here:
 
  http://mako.cc