[Qemu-devel] [PATCH] doc: Wording cleanups

[Eric Blake]

Fix several document inconsistencies (missing references,
rewrap long lines, address typos, improve grammar) introduced
in recent patches.

Signed-off-by: Eric Blake <address@hidden>

---
Note that there is still ongoing discussion about the correct
layout to use for NBD_REP_SERVER in response to NBD_OPT_INFO
(and whether the layout should be a superset of the
NBD_OPT_EXPORT_NAME reply) - cleaning that up will be a
separate patch, once consensus is reached on the best layout.
---
 doc/proto.md | 51 +++++++++++++++++++++++++++++++--------------------
 1 file changed, 31 insertions(+), 20 deletions(-)

diff --git a/doc/proto.md b/doc/proto.md
index 4d63b23..3a70209 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -445,8 +445,8 @@ during option haggling in the fixed newstyle negotiation.
       encoded data suitable for direct display to a human being; with
       no embedded or terminating NUL characters.

-    The experimental `INFO` extension (see below) is a client
-    request where the extra data has a definition other than a
+    The experimental `INFO` extension (see below) adds two client
+    option requests where the extra data has a definition other than a
     UTF-8 message.

 There are a number of error reply types, all of which are denoted by
@@ -527,7 +527,7 @@ valid may depend on negotiation during the handshake phase.
   not in fact write data (for instance on an `NBD_CMD_TRIM` in a situation
   where the command as a whole is ignored), the server MAY ignore this bit
   being set on such a command.
-- bit 1, `NBD_CMD_NO_HOLE`; defined by the experimental `WRITE_ZEROES`
+- bit 1, `NBD_CMD_FLAG_NO_HOLE`; defined by the experimental `WRITE_ZEROES`
   extension; see below.
 - bit 2, `NBD_CMD_FLAG_DF`; defined by the experimental `STRUCTURED_REPLY`
   extension; see below
@@ -608,7 +608,7 @@ The following request types exist:

     After issuing this command, a client MUST NOT make any assumptions
     about the contents of the export affected by this command, until
-    overwriting it again with `NBD_CMD_WRITE`.
+    overwriting it again with `NBD_CMD_WRITE` or `NBD_CMD_WRITE_ZEROES`.

     A client MUST NOT send a trim request unless `NBD_FLAG_SEND_TRIM`
     was set in the transmission flags field.
@@ -700,15 +700,18 @@ Therefore these commands share common documentation.

 * `NBD_OPT_INFO` and `NBD_OPT_GO`

-    `NBD_OPT_INFO`: The client wishes to get details about export with the
-    given name for use in the transmission phase, but does not yet want
-    to move to the transmission phase.
+    `NBD_OPT_INFO`: The client wishes to get details about an export
+    with the given name for use in the transmission phase, but does
+    not yet want to move to the transmission phase.  When successful,
+    this option provides more details than `NBD_OPT_LIST`, but only
+    for a single export name.

-    `NBD_OPT_GO`: The client wishes to terminate the negotiation phase and
-    progress to the transmission phase. This client MAY issue this command 
after
-    an `NBD_OPT_INFO`, or MAY issue it without a previous `NBD_OPT_INFO`.
-    `NBD_OPT_GO` can thus be used as a substitute for `NBD_OPT_EXPORT_NAME`
-    that returns errors.
+    `NBD_OPT_GO`: The client wishes to terminate the handshake phase
+    and progress to the transmission phase. This client MAY issue this
+    command after an `NBD_OPT_INFO`, or MAY issue it without a
+    previous `NBD_OPT_INFO`.  `NBD_OPT_GO` can thus be used as an
+    improved version of `NBD_OPT_EXPORT_NAME` that is capable of
+    returning errors.

     Data (both commands):

@@ -742,9 +745,9 @@ Therefore these commands share common documentation.
     - 16 bits, transmission flags.
     - 32 bits, length of name (unsigned)
     - Name of the export. This name MAY be different from the one
-      given in the `NBD_OPT_INFO` or `NBD_OPT_GO` option in case the server has
-      multiple alternate names for a single export, or a default
-      export was specified.
+      given in the `NBD_OPT_INFO` or `NBD_OPT_GO` option in case the
+      server has multiple alternate names for a single export, or a
+      default export was specified.

     The server MUST NOT fail an NDB_OPT_GO sent with the same parameters
     as a previous NBD_OPT_INFO which returned successfully (i.e. with
@@ -754,7 +757,7 @@ Therefore these commands share common documentation.
     intervening time the client has negotiated other options.
     The values of the transmission flags MAY differ from what was sent
     earlier in response to an earlier `NBD_OPT_INFO` (if any), and/or
-    the server may fail the request, based on other options that were
+    the server MAY fail the request, based on other options that were
     negotiated in the meantime.

     For backwards compatibility, clients should be prepared to also
@@ -763,14 +766,14 @@ Therefore these commands share common documentation.

     The reply to an `NBD_OPT_GO` is identical to the reply to `NBD_OPT_INFO`
     save that if the reply indicates success (i.e. is `NBD_REP_SERVER`),
-    the client and the server both immediatedly enter the transmission
+    the client and the server both immediately enter the transmission
     phase. The server MUST NOT send any zero padding bytes after the
     `NBD_REP_SERVER` data, whether or not the client negotiated the
     `NBD_FLAG_C_NO_ZEROES` flag. After sending this reply the server MUST
     immediately move to the transmission phase, and after receiving this
     reply, the client MUST immediately move to the transmission phase;
     therefore, the server MUST NOT send this particular reply until all
-    other pending option requests have been sent by the server.
+    other pending option replies have been sent by the server.

 ### `WRITE_ZEROES` extension

@@ -781,8 +784,14 @@ by a sparse file. With current NBD command set, the client 
has to issue
 through the wire. The server has to write the data onto disk, effectively
 losing the sparseness.

-To remedy this, a `WRITE_ZEROES` extension is envisioned. This extension adds
-one new command and one new command flag.
+To remedy this, a `WRITE_ZEROES` extension is envisioned. This
+extension adds one new transmission flag, one new command, and one new
+command flag.
+
+* `NBD_FLAG_SEND_WRITE_ZEROES`
+
+    The server SHOULD set this transmission flag to 1 if the
+    `NBD_CMD_WRITE_ZEROES` request is supported.

 * `NBD_CMD_WRITE_ZEROES`

@@ -817,6 +826,8 @@ The extension adds the following new command flag:
   SHOULD be set to 1 if the client wants to ensure that the server does
   not create a hole. The client MAY send `NBD_CMD_FLAG_NO_HOLE` even
   if `NBD_FLAG_SEND_TRIM` was not set in the transmission flags field.
+  The server MUST support the use of this flag if it advertises
+  `NBD_FLAG_SEND_WRITE_ZEROES`.

 ### `STRUCTURED_REPLY` extension

-- 
2.5.5