[telepathy-spec/master] Clarify Tube.Properties' definition

[Will Thompson]

---
 spec/Channel_Interface_Tube.xml |   45 ++++++++++++++++++++++++++------------
 1 files changed, 31 insertions(+), 14 deletions(-)

diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index 25be56d..0dd91a3 100644
--- a/spec/Channel_Interface_Tube.xml
+++ b/spec/Channel_Interface_Tube.xml
@@ -75,19 +75,34 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         <p>When the tube is offered, the parameters are transmitted with the
           offer and appear as a property of the incoming tube for other
           participants.</p>
-        <p>Example of valid parameters for 'smb' Server Message Block over
-          TCP/IP (from <a href="http://www.dns-sd.org/ServiceTypes.html">DNS
-          SRV (RFC 2782) Service Types
-          http://www.dns-sd.org/ServiceTypes.html</a>):
-          <code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></p>
-        <p>When requesting a channel with
-          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
-          this property MUST NOT be included in the request. This property is undefined until the tube is offered
-          (using <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Offer</tp:dbus-ref>
-          or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">Offer</tp:dbus-ref>).
-          Once it has been offered, this property MUST NOT change.</p>
+
+        <p>For example, a stream tube for <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref>
+          <tt>"smb"</tt> (<cite>Server Message Block over TCP/IP</cite>) might
+          use the following properties, as defined in <a
+          href="http://www.dns-sd.org/ServiceTypes.html">DNS SRV (RFC 2782)
+          Service Types</a>:</p>
+
+        <pre>
+{ 'u': 'some-username',
+  'p': 'top-secret-password',
+  'path': '/etc/passwd',
+}</pre>
+
+        <p>When requesting a tube with
+          <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+          this property MUST NOT be included in the request; instead, it is set
+          when <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube.DRAFT.Offer</tp:dbus-ref>
+          or <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube.DRAFT.Offer</tp:dbus-ref>
+          (as appropriate) is called. Its value is undefined until the tube is
+          offered; once set, its value MUST NOT change.</p>
+
         <p>When receiving an incoming tube, this property is immutable and so advertised in the
-          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
+          <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
           signal.</p>
       </tp:docstring>
     </property>
@@ -96,8 +111,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
               tp:name-for-bindings="State">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>State of the tube in this channel.</p>
-        <p>When requesting a channel with
-          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+
+        <p>When requesting a tube with
+          <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
           this property MUST NOT be included in the request.</p>
       </tp:docstring>
     </property>
-- 
1.5.6.5