copy edit

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1061 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0115.xml

@@ -123,19 +123,17 @@
      ver='8RovUdtOmiAjzj+xI7SK5BCw3A8='/>
 </presence>
       ]]></code>
-      <p>The 'node' attribute represents the client Romeo is using. The 'ver' attribute is a specially-constructed string that represents the identity (see &DISCOCATEGORIES;) and supported features (see &DISCOFEATURES;) of the entity.</p>
+      <p>The 'node' attribute represents the client Romeo is using (the client identifier is an "FYI" and is not used further in Entity Capabilities). The 'ver' attribute is a specially-constructed string that represents the identity (see &DISCOCATEGORIES;) and supported features (see &DISCOFEATURES;) of the entity.</p>
-      <p>At this point, your client has no idea what the capabilities are of someone with a client string 'http://exodus.jabberstudio.org/caps' and a version string '8RovUdtOmiAjzj+xI7SK5BCw3A8='. Your client therefore sends a service discovery query to Romeo, asking what his client can do.</p>
+      <p>At this point, your client has no idea what the capabilities are of someone with a version string '8RovUdtOmiAjzj+xI7SK5BCw3A8='. Your client therefore sends a service discovery query to Romeo, asking what his client can do.</p>
       <code><![CDATA[
 <iq type='get' from='juliet@capulet.lit/chamber' to='romeo@montague.lit/home' id='disco1'>
-  <query xmlns='http://jabber.org/protocol/disco#info'
+  <query xmlns='http://jabber.org/protocol/disco#info'/>
-         node='http://exodus.jabberstudio.org/caps#8RovUdtOmiAjzj+xI7SK5BCw3A8='/>
 </iq>
       ]]></code>
       <p>The response is:</p>
       <code><![CDATA[
 <iq type='result' from='romeo@montague.lit/home' to='juliet@capulet.lit/chamber' id='disco1'>
-  <query xmlns='http://jabber.org/protocol/disco#info'
+  <query xmlns='http://jabber.org/protocol/disco#info'>
-         node='http://exodus.jabberstudio.org/caps#8RovUdtOmiAjzj+xI7SK5BCw3A8='>
     <identity category='client' type='pc'/>
     <feature var='http://jabber.org/protocol/disco#info'/>
     <feature var='http://jabber.org/protocol/disco#items'/>
@@ -143,7 +141,7 @@
   </query>
 </iq>
       ]]></code>
-      <p>At this point, your client knows that anyone advertising a version string of '8RovUdtOmiAjzj+xI7SK5BCw3A8=' has a client that can do MUC. Your client remembers this information, so that it does not need to explicitly query the capabilities of a contact with the same version string. For example, Benvolio may send you the following presence:</p>
+      <p>At this point, your client knows that anyone advertising a version string of '8RovUdtOmiAjzj+xI7SK5BCw3A8=' has a client that can do &xep0045;. Your client remembers this information, so that it does not need to explicitly query the capabilities of a contact with the same version string. For example, Benvolio may send you the following presence:</p>
       <code><![CDATA[
 <presence from='benvolio@capulet.lit/230193'>
   <c xmlns='http://jabber.org/protocol/caps' 
@@ -168,7 +166,7 @@
      ver='zHyEOgxTrkpSdGcQKH8EFPLsriY='/>
 </presence>
       ]]></code>
-      <p>... you have no information about what this contact's client is capable of (as he is using a different client/version), and you therefore need to query for capabilities explicitly again via service discovery.</p>
+      <p>... you have no information about what this contact's client is capable of unless you have cached previous entity capabilities information; therefore you need to query for capabilities explicitly again via service discovery.</p>
     </section2>
   </section1>
   <section1 topic='Assumptions' anchor='assumptions'>
@@ -217,7 +215,7 @@
       </tr>
       <tr>
         <td>node</td>
-        <td>A unique identifier for the software underlying the entity, typically a URL at the website of the project or company that produces the software; required for backward-compatibility.</td>
+        <td>A unique identifier for the software underlying the entity, typically a URL at the website of the project or company that produces the software; although this information is an "FYI" in the current version of entity capabilities, it is required for backward-compatibility with older versions.</td>
         <td>REQUIRED</td>
       </tr>
       <tr>
@@ -233,19 +231,19 @@
     <p>Note: All sorting operations MUST be performed using "i;octet" collation as specified in Section 9.3 of &rfc4790;.</p>
     <ol>
       <li>Initialize an empty string S.</li>
-      <li>Sort the service discovery identities by category and then by type, formatted as "category" "/" "type".</li>
+      <li>Sort the service discovery identities by category and then by type (if it exists), formatted as "category" "/" "type".</li>
-      <li>For each identity, append the category/type (if it exists) to S, followed by the '&lt;' character.</li>
+      <li>For each identity, append the category/type to S, followed by the '&lt;' character.</li>
       <li>Sort the supported features.</li>
       <li>For each feature, append the feature to S, followed by the '&lt;' character.</li>
-      <li>Compute ver by hashing S using the SHA-1 algorithm as specified in &rfc3174; (with binary output) and encoding the hash using Base64 as specified in Section 4 of &rfc4648; (note: the Base64 output MUST NOT include whitespace and MUST set padding bits to zero).</li>
+      <li>Compute ver by hashing S using the SHA-1 algorithm as specified in &rfc3174; (with binary output) and encoding the hash using Base64 as specified in Section 4 of &rfc4648; (note: the Base64 output MUST NOT include whitespace and MUST set padding bits to zero). <note>The OpenSSL command for producing such output is "echo -n 'S' | openssl dgst -binary -sha1 | openssl enc -nopad -base64".</note></li>
     </ol>
     <p>For example, consider an entity whose service discovery category is "client", whose service discovery type is "pc", and whose supported features are "http://jabber.org/protocol/disco#info", "http://jabber.org/protocol/disco#items", and "http://jabber.org/protocol/muc". The value of the 'ver' attribute would be generated as follows:</p>
     <ol>
-      <li>E = ''</li>
+      <li>S = ''</li>
       <li>Only one identity: client/pc</li>
-      <li>E = 'client/pc&lt;'</li>
+      <li>S = 'client/pc&lt;'</li>
       <li>Sort the features: "http://jabber.org/protocol/disco#info", "http://jabber.org/protocol/disco#items", "http://jabber.org/protocol/muc".</li>
-      <li>E = 'client/pc&lt;http://jabber.org/protocol/disco#info&lt;http://jabber.org/protocol/disco#items&lt;http://jabber.org/protocol/muc&lt;'</li>
+      <li>S = 'client/pc&lt;http://jabber.org/protocol/disco#info&lt;http://jabber.org/protocol/disco#items&lt;http://jabber.org/protocol/muc&lt;'</li>
       <li>ver = 8RovUdtOmiAjzj+xI7SK5BCw3A8=</li>
     </ol>
   </section1>
@@ -328,7 +326,7 @@
   </section1>
 
   <section1 topic='Implementation Notes' anchor='impl'>
-    <p>If two entities exchanges messages but they do not normally exchange presence (i.e., via presence subscription), the entities MAY choose to send directed presence to each other, where the presence information SHOULD be annotated with the same capabilities information as each entity sends in broadcasted presence. If capabilities information has not been received from another entity, an application MUST assume that the other entity does not support capabilities.</p>
+    <p>If two entities exchange messages but they do not normally exchange presence (i.e., via presence subscription), the entities MAY choose to send directed presence to each other, where the presence information SHOULD be annotated with the same capabilities information as each entity sends in broadcasted presence. If capabilities information has not been received from another entity, an application MUST assume that the other entity does not support capabilities.</p>
   </section1>
 
   <section1 topic='Error Codes' anchor='error'>
@@ -337,7 +335,7 @@
 
   <section1 topic='Security Considerations' anchor='security'>
     <p>Use of the protocol specified in this document might make some client-specific forms of attack slightly easier, since the attacker could more easily determine the type of client being used. However, since most clients respond to <strong>jabber:iq:version</strong> requests without performing access control checks, there is no new vulnerability. Entities that wish to restrict access to capabilities information SHOULD use &xep0016; to define appropriate communications blocking (e.g., an entity MAY choose to allow IQ requests only from "trusted" entities, such as those with whom it has a subscription of "both").</p>
-    <p>Adherence to the algorithm defined in the <link url='#ver'>Generation of ver Attribute</link> sectio of this document helps to guard against poisoning of entity capabilities information by malicious or improperly implemented entities.</p>
+    <p>Adherence to the algorithm defined in the <link url='#ver'>Generation of ver Attribute</link> section of this document helps to guard against poisoning of entity capabilities information by malicious or improperly implemented entities.</p>
   </section1>
 
   <section1 topic='IANA Considerations' anchor='iana'>
@@ -391,7 +389,7 @@
   </section1>
 
   <section1 topic='Legacy Format' anchor='legacy'>
-    <p>Before Version 1.4 of this specification, the 'node' attribute was required, the 'ver' attribute was generated differently, and the 'ext' attribute was used more extensively. For historical purposes, Version 1.3 of this specification is archived at &lt;<link url='http://www.xmpp.org/extensions/attic/xep-0115-1.3.html'>http://www.xmpp.org/extensions/attic/xep-0115-1.3.html</link>&gt;. For backward-compatibility with the legacy format, the 'node' attribute is REQUIRED and the 'ext' attribute MAY be included.</p>
+    <p>Before Version 1.4 of this specification, the 'ver' attribute was generated differently and the 'ext' attribute was used more extensively. For historical purposes, Version 1.3 of this specification is archived at &lt;<link url='http://www.xmpp.org/extensions/attic/xep-0115-1.3.html'>http://www.xmpp.org/extensions/attic/xep-0115-1.3.html</link>&gt;. For backward-compatibility with the legacy format, the 'node' attribute is REQUIRED and the 'ext' attribute MAY be included.</p>
   </section1>
 
   <section1 topic='Acknowledgements' anchor='ack'>