compute-scottish-stv: fixes

[appendix-a6.git] / README.format

diff --git a/README.format b/README.format
index e08627cb0d3390524f2ec4e1d3c2fc2e0c51e0c8..88c3d7beac7eb85f9e09624f54ea3c500069eef1 100644 (file)
--- a/README.format
+++ b/README.format
@@ -2,10 +2,10 @@ We define a common election and ballot input format.
 
 Format consists of lines:
 
 
 Format consists of lines:
 

-  [| OPTION]
+  [| OPTION...]

   CAND = DESCRIPTION ... [| OPTION...]
   CAND = DESCRIPTION ... [| OPTION...]

-  VOTERNAME : CAND, (CAND=CAND=...) ... [| OPTION...]
-
+  VOTERNAME : CAND CAND=CAND=... ... [| OPTION...]
+  .

 
 We define normalised and non-normalised inputs.  Normalised is for
 input by compute programs (which do not need to check conformance with
 
 We define normalised and non-normalised inputs.  Normalised is for
 input by compute programs (which do not need to check conformance with


@@ -15,30 +15,32 @@ messing about by numans.
 In normalised files lines must occor in the order above (and
 whitespace is normalised, although readers should avoid relying on
 this other than that they may assume lack of leading and trailing
 In normalised files lines must occor in the order above (and
 whitespace is normalised, although readers should avoid relying on
 this other than that they may assume lack of leading and trailing

-whitespace on each line).
+whitespace on each line).  Normalised files always contain a
+(possibly-empty) `| OPTION' section on each line.
+
+Normalised files alwyas contain a `.' line at the end.  In
+non-normalised files anything after the `.' line is ignored, but it
+may be missing.

 
 Non-normalised files can also contain empty lines and
   # COMMENT...
 
 In non-normalised files any CAND may be omitted in which case CAND =
 CAND is assumed.  In non-normalised files an empty description is
 
 Non-normalised files can also contain empty lines and
   # COMMENT...
 
 In non-normalised files any CAND may be omitted in which case CAND =
 CAND is assumed.  In non-normalised files an empty description is

-replaced with a copy of CAND.
+replaced with a copy of CAND.  In non-normalised files there may be
+multiple lines for any one CAND (provided there is only one non-empty
+DESCRIPTION).

 
 

-CAND and VOTERNAME may contain any characters except control
-characters and 7-bit ASCII punctuation, but including ASCII
-  ampersand &
-  apostrophe '
-  hyphen -
-  full stop .
-  and underscore (_).  Processors are not required to
-generate unambiguous output when CAND or VOTERNAME contains characters
-other than 7-bit alphanumerics plus _.
+CAND and VOTERNAME may contain 7-bit alphanumerics and _..

 
 

-DESCRIPTION may contain any characters except | (and cannot contain
-leading or trailing whitespace).
+DESCRIPTION may contain any characters except | and newline (and
+cannot contain leading or trailing whitespace).

 
 VOTERNAMEs need not be distinct and may be empty.
 
 
 VOTERNAMEs need not be distinct and may be empty.
 

+Ballots may contain zero or more preferences, each being one or more
+CAND joined by `='s.  Preferences are separated by spaces.
+

 OPTION is OPTNAME[=VALUE] and modifies the preference, ballot, or whole
 election.  VALUE may contain no whitespace.
 
 OPTION is OPTNAME[=VALUE] and modifies the preference, ballot, or whole
 election.  VALUE may contain no whitespace.
 


@@ -58,10 +60,16 @@ Currently defined OPTNAMEs (default values shown)
  Election   seats=1     Number of seats to be filled.
  Election   _nodefault  For Debian A6, no default option
  Election   quorum=NUM  Quorum (default, none)
  Election   seats=1     Number of seats to be filled.
  Election   _nodefault  For Debian A6, no default option
  Election   quorum=NUM  Quorum (default, none)

+ Election   _tie=C,C>D,D  Tie break: in tie of Cs vs Ds,
+                            take Cs to have more votes than Ds.
+                            also available with <, normalised to >
+                            normalised form has Cs and Ds sorted

 
  Candidate  Super=1:1   For Debian A6, RAT:IO, 
  Candidate  default     For Debian A6, Is the default option
 
 
  Candidate  Super=1:1   For Debian A6, RAT:IO, 
  Candidate  default     For Debian A6, Is the default option
 

- Voter      Weight=1.0
+ Ballot     Weight=1.0
+ Ballot     Weight=NUM/DEN

 
 

-OPTIONs wihin a particular scope may occur in any order.
+OPTIONs wihin a particular scope may occur in any order.  Whether they
+may be repeated is up to the option.