using protocol

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

xep-0004.xml

@@ -237,7 +237,7 @@
       </tr>
       <tr>
         <td>hidden</td>
-        <td>The field is not shown to the form-submitting entity, but instead is returned with the form. The form-submitting entity SHOULD NOT modify the value of a hidden field, but MAY do so if such behavior is defined for the using protocol.</td>
+        <td>The field is not shown to the form-submitting entity, but instead is returned with the form. The form-submitting entity SHOULD NOT modify the value of a hidden field, but MAY do so if such behavior is defined for the "using protocol".</td>
       </tr>
       <tr>
         <td>jid-multi</td>
@@ -273,7 +273,12 @@
     <p>*** Note: Data provided for fields of type "text-multi" SHOULD NOT contain any newlines (the \n and \r characters). Instead, the application SHOULD split the data into multiple strings (based on the newlines inserted by the platform), then specify each string as the XML character data of a distinct &lt;value/&gt; element. Similarly, an application that receives multiple &lt;value/&gt; elements for a field of type "text-multi" SHOULD merge the XML character data of the value elements into one text block for presentation to a user, with each string separated by a newline character as appropriate for that platform.</p>
   </section2>
   <section2 topic='Multiple Items in Form Results' anchor='protocol-results'>
-    <p>In some contexts (e.g., the results of a search request), it may be necessary to communicate multiple items. Therefore, a data form of type "result" MAY contain two child elements not described in the basic syntax above: one &lt;reported/&gt; element followed by zero or more &lt;item/&gt; elements. The syntax is as follows:</p>
+    <p>In some contexts (e.g., the results of a search request), it may be necessary to communicate multiple items. Therefore, a data form of type "result" MAY contain two child elements not described in the basic syntax above:</p>
+    <ol>
+      <li>One and only &lt;reported/&gt; element, which can be understood as a "table header" describing the data to follow.</li>
+      <li>Zero or more &lt;item/&gt; elements, which can be understood as "table cells" containing data (if any) that matches the request.</li>
+    </ol>
+    <p>The syntax is as follows:</p>
     <code><![CDATA[
 <x xmlns='jabber:x:data'
    type='result'>
@@ -303,7 +308,7 @@
 </section1>
 <section1 topic='Examples' anchor='examples'>
   <p>For the sake of the following examples, let us suppose that there exists a bot hosting service on the Jabber network, located at &lt;botster.shakespeare.lit&gt;. This service enables registered users to create and configure new bots, find and interact with existing bots, and so on. We will assume that these interactions occur using the &xep0050; protocol, which is used as a "wrapper" protocol for data forms qualified by the 'jabber:x:data' namespace. The examples in the sections that follow show most of the features of the data forms protocol described above.</p>
-  <p>Note: Additional examples can be found in the specifications for various using protocols, such as <cite>XEP-0045: Multi-User Chat</cite> and <cite>XEP-0055: Jabber Search</cite>.</p>
+  <p>Note: Additional examples can be found in the specifications for various "using protocols", such as <cite>XEP-0045: Multi-User Chat</cite> and <cite>XEP-0055: Jabber Search</cite>.</p>
   <section2 topic='Configuration' anchor='examples-config'>
     <p>The first step is for a user to create a new bot on the hosting service. We will assume that this is done by sending a "create" command to the desired bot:</p>
     <example caption="User Requests Bot Creation"><![CDATA[

xep-0020.xml

@@ -95,7 +95,7 @@
   <p>Features are negotiated though the exchange of &IQ; or &MESSAGE; stanzas containing &lt;feature/&gt; child elements qualified by the 'http://jabber.org/protocol/feature-neg' namespace. However, this &lt;feature/&gt; element is simply a wrapper for structured data encapsulated in the &xep0004; protocol. <note>Earlier versions of this document defined a structured data format to handle the feature negotiation workflow; versions later than 0.4 use <cite>Data Forms</cite>, i.e., the 'jabber:x:data' namespace.</note></p>
   <p>In order to begin a negotation, the initiator sends an &IQ; stanza of type "get" (or a &MESSAGE; stanza type "normal" - see <cite>Chat Session Negotiation</cite> for examples) to the recipient with a single &lt;feature/&gt; element containing a data form of type "form" which defines the available options for one or more features. Each feature is represented as an x-data "field".</p>
   <p>The recipient SHOULD examine each feature and the values of the options provided. In order to indicate preferred values, the recipient then SHOULD specify one value for each feature and return a data form of type "submit" to the initiator in an &IQ; stanza of type "result" (or a &MESSAGE; stanza type "normal").</p>
-  <p>The following examples show some likely scenarios for feature negotiation between entities. Further examples can be found in using protocols, such as <cite>File Transfer</cite>.</p>
+  <p>The following examples show some likely scenarios for feature negotiation between entities. Further examples can be found in "using protocols", such as <cite>File Transfer</cite>.</p>
   <section2 topic="Basic Flow" anchor='protocol-basic'>
     <p>A typical negotiation flow is shown in the following example of two entities negotiating the time and place for a meeting.</p>
     <example caption="Initiating entity sends offer"><![CDATA[
@@ -223,7 +223,7 @@
     ...
   </query>
 </iq>]]></example>
-    <p>The using protocol (in these examples, &xep0045;) SHOULD specify which features might be negotiable, either in the relevant documentation or in the entry for that feature in the service discovery features registry maintained by the &REGISTRAR;. However, the initiating entity MAY also query the responding entity in order to determine which features are negotiable, as shown below.</p>
+    <p>The "using protocol" (in these examples, &xep0045;) SHOULD specify which features might be negotiable, either in the relevant documentation or in the entry for that feature in the service discovery features registry maintained by the &REGISTRAR;. However, the initiating entity MAY also query the responding entity in order to determine which features are negotiable, as shown below.</p>
     <example caption='Client queries chatroom regarding options for a negotiable feature'><![CDATA[
 <iq type='get'
     from='[email protected]/balcony'
@@ -282,7 +282,7 @@
 </section1>
 
 <section1 topic="XMPP Registrar Considerations" anchor='registrar'>
-  <p>In order for Jabber entities to adequately leverage <strong>Data Forms</strong> (e.g., by using machine-readable fields), it is RECOMMENDED to register standard x-data fields with the <cite>XMPP Registrar</cite> via the mechanisms defined in &xep0068;. Whether to do so for any given features and options shall be determined by the using protocol.</p>
+  <p>In order for Jabber entities to adequately leverage <strong>Data Forms</strong> (e.g., by using machine-readable fields), it is RECOMMENDED to register standard x-data fields with the <cite>XMPP Registrar</cite> via the mechanisms defined in &xep0068;. Whether to do so for any given features and options shall be determined by the "using protocol".</p>
 </section1>
 
 <section1 topic='XML Schema' anchor='schema'>

xep-0030.xml

@@ -473,7 +473,7 @@
     </section2>
     <section2 topic='Items Nodes' anchor='items-nodes'>
       <p>It is possible that an item associated with an entity will not be addressable as a JID; examples might include offline messages stored in an inbox (see &xep0013;), entries in a Jabber-enabled weblog, XML-RPC services associated with a client or component, items available in an online trading system (e.g., a catalog or auction), news postings located at an NNTP gateway, and topics hosted by a &xep0060; component. In order to handle such items, the &lt;item/&gt; element MAY possess an OPTIONAL 'node' attribute that supplements the REQUIRED 'jid' attribute.</p>
-      <p>The value of the node attribute may or may not have semantic meaning; from the perspective of Service Discovery, a node is merely something that is associated with an entity. In order to discover more about the node, the requesting entity MUST query the entity's JID while specifying the node. If the value of the 'node' attribute has semantic meaning, that meaning is provided by the using protocol or application, not by the Service Discovery protocol. A node attribute SHOULD NOT be included unless it is necessary to provide or discover information about an entity that cannot be directly addressed as a JID (i.e., if the associated item can be addressed as a JID, do not include a node). The value of the 'node' attribute MUST NOT be null.</p>
+      <p>The value of the node attribute may or may not have semantic meaning; from the perspective of Service Discovery, a node is merely something that is associated with an entity. In order to discover more about the node, the requesting entity MUST query the entity's JID while specifying the node. If the value of the 'node' attribute has semantic meaning, that meaning is provided by the "using protocol" or application, not by the Service Discovery protocol. A node attribute SHOULD NOT be included unless it is necessary to provide or discover information about an entity that cannot be directly addressed as a JID (i.e., if the associated item can be addressed as a JID, do not include a node). The value of the 'node' attribute MUST NOT be null.</p>
       <p>In the following example, a user requests all available items from an online catalog service:</p>
       <example caption='Requesting nodes'><![CDATA[
 <iq type='get'
@@ -846,7 +846,7 @@
         </section4>
       </section3>
       <section3 topic='Well-Known Nodes' anchor='registrar-reg-nodes'>
-        <p>A using protocol may specify one or more service discovery nodes that have a special and well-defined meaning in the context of that protocol. For the purpose of reserving these node names globally across all Jabber protocols, the XMPP Registrar maintains a registry of well-known service discovery nodes at &NODES;.</p>
+        <p>A "using protocol" may specify one or more service discovery nodes that have a special and well-defined meaning in the context of that protocol. For the purpose of reserving these node names globally across all Jabber protocols, the XMPP Registrar maintains a registry of well-known service discovery nodes at &NODES;.</p>
         <section4 topic='Process' anchor='registrar-reg-nodes-process'>
           &REGPROCESS;
           <code><![CDATA[

xep-0059.xml

@@ -498,7 +498,7 @@
 </iq>
   ]]></example>
   <p>An entity SHOULD NOT include the result set management extensions defined in this document in its requests if it does not have positive knowledge that the responding entity supports the protocol defined herein. If the responding entity does not understand result set management, it MUST ignore such extensions.</p>
-  <p>Note: Even if a responding entity understands the result set management protocol, its support for result set management in the context of any given using protocol is OPTIONAL (e.g., an implementation could support it in the context of the 'jabber:iq:search' namespace but not in the context of the 'http://jabber.org/protocol/disco#items' namespace). Currently the only way for a requesting entity to determine if a responding entity supports result set management in the context of a given using protocol is to include result set management extensions in its request. If the responding entity does not include result set management extensions in its response, then the requesting entity SHOULD NOT include such extensions in future requests wrapped by the using protocol namespace.</p>
+  <p>Note: Even if a responding entity understands the result set management protocol, its support for result set management in the context of any given "using protocol" is OPTIONAL (e.g., an implementation could support it in the context of the 'jabber:iq:search' namespace but not in the context of the 'http://jabber.org/protocol/disco#items' namespace). Currently the only way for a requesting entity to determine if a responding entity supports result set management in the context of a given "using protocol" is to include result set management extensions in its request. If the responding entity does not include result set management extensions in its response, then the requesting entity SHOULD NOT include such extensions in future requests wrapped by the "using protocol" namespace.</p>
 </section1>
 <section1 topic='Security Considerations' anchor='security'>
   <p>Security considerations are the responsibility of the using ("wrapper") protocol, such as <cite>XEP-0030</cite> for the 'http://jabber.org/protocol/disco#items' namespace, <cite>XEP-0055</cite> for the 'jabber:iq:search' namespace, and <cite>XEP-0136</cite> for the 'http://jabber.org/protocol/archive' namespace.</p>

xep-0131.xml

@@ -242,7 +242,7 @@
   <p>However, many Internet standards use a different datetime format that ultimately derives from &rfc0822; as updated by &rfc1123;; specifically, that format is used by email (<cite>RFC 2822</cite>), the World Wide Web (<cite>RFC 2616</cite>), and the Session Initiation Protocol (<cite>RFC 3261</cite>). To map dates to and from these protocols, we define the SHIM RFC2822Date header.</p>
 </section1>
 <section1 topic='Security Considerations' anchor='security'>
-  <p>In general, security considerations are the responsibility of the using protocol.</p>
+  <p>In general, security considerations are the responsibility of the "using protocol".</p>
   <p>Certain SHIM headers MAY be security-sensitive (e.g., the "Classification", "Distribute", and "Store" headers specified herein). If an entity plans to use such headers, it MUST determine whether the intended recipient supports both the SHIM protocol and the particular security-sensitive headers of interst, as described under <link url='#disco'>Service Discovery</link>; furthermore, an implementation MUST warn a human user (if any) before use if the security-sensitive headers of interest are not supported.</p>
 </section1>
 <section1 topic='IANA Considerations' anchor='iana'>

xep-0147.xml

@@ -226,7 +226,7 @@ xmpp:[email protected]?unsubscribe
 </section1>
 <section1 topic='Internationalization Considerations' anchor='i18n'>
   <p>Internationalization considerations for XMPP IRIs/URIs are specified in <cite>RFC 4622</cite>; the reader is referred to that document for a complete discussion of the relevant issues.</p>
-  <p>Localization of application-specific data presented to a human user (e.g., as encapsulated in key-value pairs) is the responsibility of the using protocol.</p>
+  <p>Localization of application-specific data presented to a human user (e.g., as encapsulated in key-value pairs) is the responsibility of the "using protocol".</p>
 </section1>
 <section1 topic='Security Considerations' anchor='security'>
   <p>Security considerations for XMPP IRIs/URIs are specified in <cite>RFC 4622</cite>.</p>

xep-0221.xml

@@ -31,7 +31,7 @@
 </header>
 
 <section1 topic='Introduction' anchor='intro'>
-  <p>In certain protocols that make use of &xep0004;, it can be helpful to include media data such as small images. One example of such a using protocol is &xep0158;. This document defines a method for including media data in a data form.</p>
+  <p>In certain protocols that make use of &xep0004;, it can be helpful to include media data such as small images. One example of such a "using protocol" is &xep0158;. This document defines a method for including media data in a data form.</p>
 </section1>
 
 <section1 topic='Media Element' anchor='media'>