README.format

   1 We define a common election and ballot input format.
   2
   3 Format consists of lines:
   4
   5   [| OPTION...]
   6   CAND = DESCRIPTION ... [| OPTION...]
   7   VOTERNAME : CAND CAND=CAND=... ... [| OPTION...]
   8   .
   9
  10 We define normalised and non-normalised inputs.  Normalised is for
  11 input by compute programs (which do not need to check conformance with
  12 the syntax) and non-normalised is for output from converters and
  13 messing about by numans.
  14
  15 In normalised files lines must occor in the order above (and
  16 whitespace is normalised, although readers should avoid relying on
  17 this other than that they may assume lack of leading and trailing
  18 whitespace on each line).  Normalised files always contain a
  19 (possibly-empty) `| OPTION' section on each line.
  20
  21 Normalised files alwyas contain a `.' line at the end.  In
  22 non-normalised files anything after the `.' line is ignored, but it
  23 may be missing.
  24
  25 Non-normalised files can also contain empty lines and
  26   # COMMENT...
  27
  28 In non-normalised files any CAND may be omitted in which case CAND =
  29 CAND is assumed.  In non-normalised files an empty description is
  30 replaced with a copy of CAND.  In non-normalised files there may be
  31 multiple lines for any one CAND (provided there is only one non-empty
  32 DESCRIPTION).
  33
  34 CAND and VOTERNAME may contain 7-bit alphanumerics and _..
  35
  36 DESCRIPTION may contain any characters except | and newline (and
  37 cannot contain leading or trailing whitespace).
  38
  39 VOTERNAMEs need not be distinct and may be empty.
  40
  41 Ballots may contain zero or more preferences, each being one or more
  42 CAND joined by `='s.  Preferences are separated by spaces.
  43
  44 OPTION is OPTNAME[=VALUE] and modifies the preference, ballot, or whole
  45 election.  VALUE may contain no whitespace.
  46
  47 OPTNAME contains only alphanumerics (or _) and starts with a letter or
  48 _.  Reader should treat unknown OPTNAMEs as follows:
  49   starts with uppercase letter - crash (reject the input file)
  50   starts with lowercase letter - generate a warning
  51   starts with underscore - silently ignore
  52
  53 Anything which expects a particular OPTNAME should usually accept all
  54 three variants, with a regexp like /^_?[Qq]orum=(\d+)$/.  Convention
  55 is _-separated words, with inner words being in lowercase, even when
  56 OPTNAME starts with a capital.
  57
  58 Currently defined OPTNAMEs (default values shown)
  59
  60  Election   seats=1     Number of seats to be filled.
  61  Election   _nodefault  For Debian A6, no default option
  62  Election   quorum=NUM  Quorum (default, none)
  63  Election   _tie=C,C>D,D  Tie break: in tie of Cs vs Ds,
  64                             take Cs to have more votes than Ds.
  65                             also available with <, normalised to >
  66                             normalised form has Cs and Ds sorted
  67
  68  Candidate  Super=1:1   For Debian A6, RAT:IO,
  69  Candidate  default     For Debian A6, Is the default option
  70
  71  Ballot     Weight=1.0
  72  Ballot     Weight=NUM/DEN
  73
  74 OPTIONs wihin a particular scope may occur in any order.  Whether they
  75 may be repeated is up to the option.