docs

[appendix-a6.git] / compute

diff --git a/compute b/compute
index 6400382c45a97e726dcb1cfa35cce2a7d74e6c2b..c544437bdb05468ed7f94076829c884d609a54f4 100755 (executable)
--- a/compute
+++ b/compute
@@ -4,8 +4,50 @@
 # to Debian Constitution A.6.
 #
 # usage: .../compute [<input files>...]
+#  (uses stdin if none supplied)
 #
-# 
+# input files can be in any order and should contain lines like:
+#
+#   <votername> :: <PREF>, (<PREF>=<PREF>), <PREF>, ....
+#   V: <tallyprefs> <votername>
+#   <ABBREV> = <description...>
+#   <ABBREV> = <description...> [<rat>:<io>]
+#   <ABBREV> = <description...> [default]
+#   nodefault
+#   quorum = <quorum>
+#
+# where
+#
+#   <votername> is any non-whitespace characters
+#
+#   <ABBREV> and <PREF> are abbreviations for choices on the ballot.
+#      They must be ASCII alphanumeric.  Numeric preferences are
+#      not recommended as they are confusing (particularly when
+#      tally sheets are in use).
+#
+#      It is best to avoid FD, SQ and NOTA except for the default
+#      option; if no default option is specified, it will default
+#      to one of these unless a "nodefault" line is found.
+#
+#      In the "::" form, the commas are optional.  Either ( ) or = may
+#      be used to indicate a set of equal preferences.
+#
+#   <tallyprefs> is a tally sheet preference order: that is,
+#      a single uppercase base36 digit for each ballot choice,
+#      (in the order they were specified by "=" lines), giving
+#      the voter's preference rank for that option.  The numbers
+#      need not be distinct or contiguous.  "-" may be used for
+#      unranked preferences.
+#
+#   <rat>:<io> is the majority ratio for the option
+#
+#   <quorum> is the quorum
+#
+# and also allowed are
+#
+#   #-comments                            } all
+#   blank lines                           } ignored
+#   lines starting with whitespace        }
 
 use strict;
 use utf8;
@@ -127,7 +169,7 @@ if ($defcho && $defcho->{Index} > -1) {
        last if $defcho;
     }
     if ($defcho) {
-       print "guessed default option was: $choices[$defcho->{Index}]\n";
+       print "guessed default option: $choices[$defcho->{Index}]\n";
     } else {
        print "could not guess default option, assuming there is none\n";
     }
@@ -280,6 +322,10 @@ for (;;) {
 
     my $tdefeats = $defeats->transitive_closure();
 
+    # this makes the debugging output prettier
+    foreach my $ch (@choices) {
+       $tdefeats->delete_edge($ch,$ch);
+    }
     print "closure graph: $tdefeats\n";
 
     print "\nSchwartz set A.6(6)\n";