Address some feedback on entity versioning

inbox/entityversioning.xml

@@ -144,8 +144,7 @@
   </section2>
 </section1>
 
-<section1 topic='Protocol' anchor='proto'>
+<section1 topic='Discovering Support' anchor='disco'>
-  <section2 topic='Discovering Support' anchor='disco'>
     <p>
       If a server supports entity versioning, it MUST inform the connecting
       client when returning stream features during the stream negotiation
@@ -166,14 +165,14 @@
     The entity versioning stream feature is merely informative and therefore
     is never mandatory-to-negotiate.
   </p>
-</section2>
+</section1>
 
-  <section2 topic='Version Tokens' anchor='version_tokens'>
+<section1 topic='Version Tokens' anchor='version_tokens'>
   <p>
-      Version tokens are short case-sensitive strings which are generated by
+    Version tokens are short case-sensitive strings which are generated by the
-      the server. Their format is not defined in this spec, but a
+    server. Their format is not defined in this spec, but a recommendation may
-      recommendation may be found in the Implementation Notes. Version tokens
+    be found in the <link url="#impl">Implementation Notes</link>. Version
-      are akin to a weakly-validated etag for the entity in question.
+    tokens are akin to a weakly-validated etag for the entity in question.
   </p>
   <p>
     Servers that implement this protocol must assign such a version token to
@@ -271,8 +270,8 @@
     Clients that implement this protocol SHOULD then cache the entity in
     question when a version token is received.
   </p>
-</section2>
+
-<section2 topic='Cache Invalidation' anchor='deletes'>
+  <section2 topic='Cache Invalidation' anchor='deletes'>
     <p>
       When a client syncs with the server and indicates that it has a version
       token in its cache that does not match any entity on the server (or when
@@ -283,8 +282,8 @@
       removal of 'inverness@chat.shakespeare.lit' from the cached MUC list:
 
       <example caption="MUC deletion"><![CDATA[
-<!-- Client -->
+  <!-- Client -->
-<iq from='hag66@shakespeare.lit/phone'
+  <iq from='hag66@shakespeare.lit/phone'
       id='zb8q41fas6yn4'
       to='chat.shakespeare.lit'
       type='get'>
@@ -296,10 +295,10 @@
         <version xmlns='urn:xmpp:entityver:0'>4OLGSVNY</version>
       </item>
     </query>
-</iq>
+  </iq>
 
-<!-- Server -->
+  <!-- Server -->
-<iq from='chat.shakespeare.lit'
+  <iq from='chat.shakespeare.lit'
     id='zb8q41fas6yn4'
     to='hag66@shakespeare.lit/phone'
     type='result'>
@@ -308,7 +307,7 @@
         <version xmlns='urn:xmpp:entityver:0'/>
       </item>
     </query>
-</iq>
+  </iq>
       ]]></example>
     </p>
     <p>
@@ -316,8 +315,9 @@
       list by any other means (eg. via a roster push), it SHOULD remove the
       version token associated with that entity from its cache.
     </p>
-</section2>
+  </section2>
-<section2 topic='Aggregate Tokens' anchor='agg_tokens'>
+</section1>
+<section1 topic='Aggregate Tokens' anchor='agg_tokens'>
   <p>
     While the version token approach to caching does not require a great deal
     of state to be stored on the client or the server, it does require a lot
@@ -327,9 +327,11 @@
     avoid sending the large request entirely). To do this, we can request an
     aggregate version token from the server. This aggregate token is calculated
     by constructing a string of comma separated "bare JID:version" pairs sorted
-    in byte-wise order, and taking the MD5 hash of the constructed string. For
+    in byte-wise order (because the JID:version pair is constructed before
-    example, if the server is calculating the aggregate version token for a
+    sorting, if two items in the list have the same JID they can still be
-    roster, it might end up with the following string:
+    sorted by the version token), and taking the MD5 hash of the constructed
+    string. For example, if the server is calculating the aggregate version
+    token for a roster, it might end up with the following string:
   </p>
   <example caption="Aggregate token list"><![CDATA[
 anne@shakespeare.lit:VIZSVF0D,bill@shakespeare.lit:25P2A7H8
@@ -344,25 +346,26 @@ anne@shakespeare.lit:VIZSVF0D,bill@shakespeare.lit:25P2A7H8
     The actual request is an IQ sent to the server, or entity handling the
     versioned list which contains a query that specifies the namespace of the
     list we want to fetch. Eg. to fetch the aggregate token for the roster one
-    would query the server:
+    would query the server with the type set to the `jabber:iq:roster`
+    namespace:
   </p>
   <example caption="Roster aggregate token request"><![CDATA[
-
+<!-- Client -->
-    <!-- Client -->
+<iq to='bill@shakespeare.lit' type='get' id='bill1'>
-    <iq to='bill@shakespeare.lit' type='get' id='bill1'>
   <query xmlns='urn:xmpp:entityver:0' type='jabber:iq:roster' />
-    </iq>
+</iq>
 
-    <!-- Server -->
+<!-- Server -->
-    <iq to='bill@shakespeare.lit/home' type='result' id='bill1'>
+<iq to='bill@shakespeare.lit/home' type='result' id='bill1'>
   <query xmlns='urn:xmpp:entityver:0' type='jabber:iq:roster'>
     0514fc90e6c7981b06bbb2173bb8ef03
   </query>
-    </iq>
+</iq>
   ]]></example>
   <p>
     Similarly, to fetch the aggregate token for a list of MUC rooms, one would
-    query the MUC component directly:
+    query the MUC component directly with the type set to the 'disco#items'
+    namespace:
   </p>
   <example caption="MUC rooms aggregate token request"><![CDATA[
     <!-- Client -->
@@ -382,13 +385,18 @@ anne@shakespeare.lit:VIZSVF0D,bill@shakespeare.lit:25P2A7H8
     to a normal request if any error is returned in response to an aggregate
     token IQ.
   </p>
+  <p>
+    If an aggregate token is requested for a list that may contain more than
+    one type of entity (eg. MUC rooms and pubsub nodes that live on the same
+    component), then the server MUST return the aggregate token constructed
+    with the entire list (rooms and pubsub nodes).
+  </p>
   <p>
     Clients are also NOT REQUIRED to check aggregate tokens. However, clients
     MAY wish to check aggregate tokens before making a roster or MUC request
     when the cached roster or MUC list is very large. When to check aggregate
-    tokens is left up to the clients.
+    tokens (if at all) is left up to the implementation.
   </p>
-</section2>
 </section1>
 
 <section1 topic='Implementation Notes' anchor='impl'>