docs(CLI): inforamtion about setting structs

For now we just have a 'dum' example, but once we are there, we shall
make the example and documentation based on the actual request value.

This requires some additional work, which fortunately has to be done
in python only.

src/mako/cli/docs/commands.md.mako

@@ -2,7 +2,7 @@
 <%
     from util import (hash_comment, new_context, method_default_scope, indent_all_but_first_by)
     from cli import (subcommand_md_filename, new_method_context, SPLIT_START, SPLIT_END, pretty, SCOPE_FLAG,
-                     mangle_subcommand, is_request_value_property)
+                     mangle_subcommand, is_request_value_property, FIELD_SEP)
 
     c = new_context(schemas, resources, context.get('methods'))
 %>\
@@ -42,6 +42,36 @@ You can set the scope for this method like this: `${util.program_name()} --${SCO
     - ${p.get('description') or 'No description provided' | indent_all_but_first_by(2)}
 % endfor  # each required property (which is not the request value)
 % endif # have required properties
+% if mc.request_value:
+# Required Request Value
+
+The request value is a data-structure with various fields. Each field may be a simple scalar or another data-structure.
+In the latter case it is advised to set the field-cursor to the data-structure's field to specify values more concisely.
+
+For example, a structure like this:
+```
+"scalar_int": 5,
+"struct": {
+    "scalar_float": 2.4
+    "sub_struct": {
+        "strings": ["baz", "bar"],
+        "mapping": HashMap,
+    }
+}
+"scalar_str": "foo",
+```
+
+can be set completely with the following arguments. Note how the cursor position is adjusted the respective fields:
+```
+-r scalar_int=2 -r struct -r scalar_float=4.2 -r sub_struct -r strings=first -r strings=second -r mapping=key=value -r ${FIELD_SEP} -r scalar_str=other
+```
+
+* The cursor position is always set relative to the current one, unless the field name starts with the '${FIELD_SEP}' character. Fields can be nested such as in `-r f${FIELD_SEP}s${FIELD_SEP}o` .
+* **Lists** are always appended to, in the example, the list at `struct${FIELD_SEP}sub_struct${FIELD_SEP}strings` will have the value `["first", "second"]`.
+* **Mappings** are set using the `key=value` form.
+* You can also set nested fields without setting the cursor explicitly. For example, to set the mapping from the root, you would specify `-r struct${FIELD_SEP}sub_struct${FIELD_SEP}mapping=foo=bar`. In case the cursor is not at the root, you may explicitly drill down from the root using a leading '${FIELD_SEP}' character.
+
+% endif # have request value
 ${SPLIT_END}
 % endfor # each method
 % endfor # each resource

src/mako/cli/lib/cli.py

@@ -14,6 +14,8 @@ OUTPUT_FLAG = 'o'
 VALUE_ARG = 'v'
 SCOPE_FLAG = 'scope'
 
+FIELD_SEP = '.'
+
 CONFIG_DIR = '~/.google-service-cli'
 
 re_splitters = re.compile(r"%s ([\w\-\.]+)\n(.*?)\n%s" % (SPLIT_START, SPLIT_END), re.MULTILINE|re.DOTALL)

src/mako/cli/lib/docopt.mako

@@ -2,7 +2,7 @@
 <%!
     from util import (put_and, supports_scopes)
     from cli import (mangle_subcommand, new_method_context, PARAM_FLAG, STRUCT_FLAG, UPLOAD_FLAG, OUTPUT_FLAG, VALUE_ARG,
-                     CONFIG_DIR, SCOPE_FLAG, is_request_value_property)
+                     CONFIG_DIR, SCOPE_FLAG, is_request_value_property, FIELD_SEP)
 
     v_arg = '<%s>' % VALUE_ARG
     file_arg = '<file>'
@@ -63,9 +63,9 @@ Usage:
 Options:
 % if struct_used:
     -${STRUCT_FLAG} ${v_arg}  set request structure field;
-            ${v_arg} supports cursor form 'field[:subfield]...' to 
+            ${v_arg} supports cursor form 'field[${FIELD_SEP}subfield]...' to 
             set the curor for upcoming values and supports the value form
-            'field[:subfield]...=value' to set an actual field.
+            'field[${FIELD_SEP}subfield]...=value' to set an actual field.
 % endif
 % if upload_protocols_used:
     -${UPLOAD_FLAG}  <mode> ${file_arg} ${mime_arg}