[PATCH 1 of 7] bundle2: clarify stream parameter design in the documentation

[pierre-yves.david at ens-lyon.org]

# HG changeset patch
# User Pierre-Yves David <pierre-yves.david at fb.com>
# Date 1395346714 25200
#      Thu Mar 20 13:18:34 2014 -0700
# Node ID 87d3a675a99914ba3371debbdd5de6a96c58523a
# Parent  c5aaeca0cfbfaad91eaa9c1a40f04b424bce2bd9
bundle2: clarify stream parameter design in the documentation

Stream level parameter have very restricted use case. Clarify why we chosen a
textual format and point that applicative data goes in applicative parts.

diff --git a/mercurial/bundle2.py b/mercurial/bundle2.py
--- a/mercurial/bundle2.py
+++ b/mercurial/bundle2.py
@@ -46,11 +46,18 @@ Binary format is as follow
 
   Parameter value are not supported yet.
 
   Special character in param name are not supported yet.
 
+  Stream parameters use a simple textual format for two main reasons:
 
+  - Stream level parameters should remains simple and we want to discourage any
+    crazy usage.
+  - Textual data allow easy human inspection of a the bundle2 header in case of
+    troubles.
+
+  Any Applicative level options MUST go into a bundle2 part instead.
 
 
 Payload part
 ------------------------