docs

diff --git a/compute b/compute
index a58e2505cc5b7f3006732ede785763be54d6b5f9..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;