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).
  19
  20 Non-normalised files can also contain empty lines and
  21   # COMMENT...
  22
  23 In non-normalised files any CAND may be omitted in which case CAND =
  24 CAND is assumed.  In non-normalised files an empty description is
  25 replaced with a copy of CAND.
  26
  27 CAND and VOTERNAME may contain any characters except control
  28 characters and 7-bit ASCII punctuation, but including ASCII
  29   ampersand &
  30   apostrophe '
  31   hyphen -
  32   full stop .
  33   and underscore (_).  Processors are not required to
  34 generate unambiguous output when CAND or VOTERNAME contains characters
  35 other than 7-bit alphanumerics plus _.
  36
  37 DESCRIPTION may contain any characters except | (and cannot contain
  38 leading or trailing whitespace).
  39
  40 VOTERNAMEs need not be distinct and may be empty.
  41
  42 OPTION is OPTNAME[=VALUE] and modifies the preference, ballot, or whole
  43 election.  VALUE may contain no whitespace.
  44
  45 OPTNAME contains only alphanumerics (or _) and starts with a letter or
  46 _.  Reader should treat unknown OPTNAMEs as follows:
  47   starts with uppercase letter - crash (reject the input file)
  48   starts with lowercase letter - generate a warning
  49   starts with underscore - silently ignore
  50
  51 Anything which expects a particular OPTNAME should usually accept all
  52 three variants, with a regexp like /^_?[Qq]orum=(\d+)$/.  Convention
  53 is _-separated words, with inner words being in lowercase, even when
  54 OPTNAME starts with a capital.
  55
  56 Currently defined OPTNAMEs (default values shown)
  57
  58  Election   seats=1     Number of seats to be filled.
  59  Election   _nodefault  For Debian A6, no default option
  60  Election   quorum=NUM  Quorum (default, none)
  61
  62  Candidate  Super=1:1   For Debian A6, RAT:IO,
  63  Candidate  default     For Debian A6, Is the default option
  64
  65  Voter      Weight=1.0
  66
  67 OPTIONs wihin a particular scope may occur in any order.