[Telepathy-commits] [telepathy-spec/master] Better introduction to Chan.Iface.Tube, thanks to wjt

[Alban Crequy]

---
 spec/Channel_Interface_Tube.xml |   25 ++++++++++++++++---------
 1 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index d3c4e66..aa69e44 100644
--- a/spec/Channel_Interface_Tube.xml
+++ b/spec/Channel_Interface_Tube.xml
@@ -21,16 +21,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       tp:causes-havoc="experimental">
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>A "tube" is a mechanism for arbitrary data transfer. A tube channel
-        can contain only one tube. This interface contains the properties,
-        signals and methods common to all types of tubes. One cannot create a
-        tube channel of type org.freedesktop.Telepathy.Channel.Interface.Tube
-        but only channels of a specific type tube channel. Only stream and
-        D-Bus tubes exist currently. They have their own interface and their
-        interface can be used to create a tube channel.</p>
+      <p>A <i>tube</i> is a mechanism for arbitrary data transfer between
+      two or more IM users, used to allow applications on the users'
+      systems to communicate without having to establish network
+      connections themselves. Currently, two types of tube exist:
+      <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+      >Channel.Type.DBusTube</tp:dbus-ref> and
+      <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+      >Channel.Type.StreamTube</tp:dbus-ref>. This interface contains
+      the properties, signals and methods common to both types of tube;
+      you can only create channels of a specific tube type, not of this
+      type. A tube channel contains exactly one tube; if you need several
+      tubes, you have to create several tube channels.</p>
 
-      <p>The Tubes channel type may be requested for handles of type
-        HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.</p>
+      <p>Tube channels can be requested for handles of type
+      HANDLE_TYPE_CONTACT (for 1-1 communication) or of type
+      HANDLE_TYPE_ROOM (to communicate with others in the room
+      simultaneously).</p>
     </tp:docstring>
 
     <property name="Initiator" type="u" tp:type="Contact_Handle" access="read"
-- 
1.5.6.5