Doc: add client voting commands

docs/whitedoc/voting.rst

@@ -5,7 +5,7 @@ The Voting Process
 
 The design of the Tezos Node allows the consensus protocol to be
 amended, that is replaced by another set of OCaml files which
-implements the API of a valid protocol.
+implement the API of a valid protocol.
 
 In the current protocol the amendment procedure is guided by a voting
 procedure where delegates can propose, select and test a candidate
@@ -65,12 +65,13 @@ the current participation with the following coefficients::
 
   newQ = oldQ * 8/10 + participation * 2/10
 
-More details can be found in the file ``amendment.ml``.
+More details can be found in the file
+``src/proto_alpha/lib_protocol/src/amendment.ml``.
 
 Operations
 ----------
 
-There two operations used by the delegates: ``proposals`` and ``ballot``.
+There are two operations used by the delegates: ``proposals`` and ``ballot``.
 A proposal operation can only be submitted during a proposal period.
 
 ::
@@ -104,5 +105,77 @@ The pass vote allows a delegate to not influence a vote but still
 allowing it to reach quorum.
 
 More details can be found, as for all operations, in
-``operation_repr.ml``. The binary format is described by
+``src/proto_alpha/lib_protocol/src/operation_repr.ml``.
-``tezos-client describe unsigned operation``.
+The binary format is described by ``tezos-client describe unsigned
+operation``.
+
+Client Commands
+---------------
+
+Tezos' client provides a command to show the status of a voting period.
+It displays different informations for different kind of periods, as
+in the following samples::
+
+  $ tezos-client show voting period
+  Current period: "proposal"
+  Blocks remaining until end of period: 59
+  Current proposals:
+  PsNa6jTtsRfbGaNSoYXNTNM5A7c3Lji22Yf2ZhpFUjQFC17iZVp 400
+
+  $ tezos-client show voting period
+  Current period: "testing_vote"
+  Blocks remaining until end of period: 63
+  Current proposal: PsNa6jTtsRfbGaNSoYXNTNM5A7c3Lji22Yf2ZhpFUjQFC17iZVp
+  Ballots: { "yay": 400, "nay": 0, "pass": 0 }
+  Current participation 20.00%, necessary quorum 80.00%
+  Current in favor 400, needed supermajority 320
+
+  $ tezos-client show voting period
+  Current period: "testing"
+  Blocks remaining until end of period: 64
+  Current proposal: PsNa6jTtsRfbGaNSoYXNTNM5A7c3Lji22Yf2ZhpFUjQFC17iZVp
+
+It should be noted that the number 400 above is a number of rolls.
+The proposal has a total of 400 rolls, which may come from several
+delegates. The same applies for the ballots, there are 400 rolls in
+favor of testing protocol PsNa6jTt.
+
+Submit proposals
+~~~~~~~~~~~~~~~~
+
+During a proposal period, the list of proposals can be submitted with::
+
+    tezos-client submit proposals for <delegate> <proposal1> <proposal2> ...
+
+Remember that each delegate can submit a maximum of 20 protocol
+hashes including duplicates.
+Moreover each proposal is accepted only if it meets one of the
+following two conditions:
+
+- the protocol hash was already proposed on the network. In this case
+  we can submit an additional proposal that "upvotes" an existing one
+  and our rolls are added to the ones already supporting the proposal.
+- the protocol is known by the node. In particular the first proposer
+  of a protocol should be able to successfully inject the protocol in
+  its node which performs some checks, compiles and loads the
+  protocol.
+
+Submit ballots
+~~~~~~~~~~~~~~
+
+During a voting period, being it a testing vote or a promotion vote,
+ballots can be submitted once with::
+
+    tezos-client submit ballot for <delegate> <proposal> <yay|nay|pass>
+
+Other resources
+~~~~~~~~~~~~~~~
+
+For more details on the client commands refer to the manual at
+:ref:`client_manual`.
+
+For vote related RPCs check the :ref:`rpc_index` under the prefix
+``vote/``.
+
+For Ledger support refer to Obsidian Systems' `documentation
+<https://github.com/obsidiansystems/ledger-app-tezos#proposals-and-voting>`_.