Address some feedback on entity versioning

inbox/entityversioning.xml

@@ -144,8 +144,7 @@
   </section2>
 </section1>
 
-<section1 topic='Protocol' anchor='proto'>
-  <section2 topic='Discovering Support' anchor='disco'>
+<section1 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
-      the server. Their format is not defined in this spec, but a
-      recommendation may be found in the Implementation Notes. Version tokens
-      are akin to a weakly-validated etag for the entity in question.
+    Version tokens are short case-sensitive strings which are generated by the
+    server. Their format is not defined in this spec, but a recommendation may
+    be found in the <link url="#impl">Implementation Notes</link>. Version
+    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,7 +270,7 @@
     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'>
     <p>
       When a client syncs with the server and indicates that it has a version
@@ -317,7 +316,8 @@
       version token associated with that entity from its cache.
     </p>
   </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
-    example, if the server is calculating the aggregate version token for a
-    roster, it might end up with the following string:
+    in byte-wise order (because the JID:version pair is constructed before
+    sorting, if two items in the list have the same JID they can still be
+    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,10 +346,10 @@ 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 -->
 <iq to='bill@shakespeare.lit' type='get' id='bill1'>
   <query xmlns='urn:xmpp:entityver:0' type='jabber:iq:roster' />
@@ -362,7 +364,8 @@ anne@shakespeare.lit:VIZSVF0D,bill@shakespeare.lit:25P2A7H8
   ]]></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'>