Update to tp-spec head

20080717154511-93b9a-116972b240dc055f91ef95b430c427cb4e1e22a1.gz

12 files changed, 511 insertions, 262 deletions

diff --git a/spec/Account.xml b/spec/Account.xml
index 5521f5ccc..86ff67582 100644
--- a/spec/Account.xml
+++ b/spec/Account.xml
@@ -298,36 +298,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:possible-errors>
     </method>
 
-    <tp:struct name="Account_Presence">
-      <tp:docstring>
-        A simplified form of the presence statuses seen in the Presence
-        interface.
-      </tp:docstring>
-
-      <tp:member name="Type" type="u" tp:type="Connection_Presence_Type">
-        <tp:docstring>
-          The presence type, e.g. Connection_Presence_Type_Away.
-        </tp:docstring>
-      </tp:member>
-
-      <tp:member name="Status" type="s">
-        <tp:docstring>
-          The connection-manager-specific string identifier of the presence
-          status, e.g. "brb".
-        </tp:docstring>
-      </tp:member>
-
-      <tp:member name="Message" type="s">
-        <tp:docstring>
-          The user-defined status message, e.g. "Back soon!". This will be
-          used as the value for the 'message' keyword in the Presence
-          interface's dictionary, if possible.
-        </tp:docstring>
-      </tp:member>
-    </tp:struct>
-
     <property name="AutomaticPresence" type="(uss)" access="readwrite"
-      tp:type="Account_Presence">
+      tp:type="Simple_Presence">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The presence status that this account should have if it is brought
           online.</p>
@@ -405,7 +377,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
     </property>
 
     <property name="CurrentPresence" type="(uss)" access="read"
-      tp:type="Account_Presence">
+      tp:type="Simple_Presence">
       <tp:docstring>
         The actual presence. If the connection is not online, this should be
         (Connection_Presence_Type_Offline, "", "").
@@ -421,7 +393,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
     </property>
 
     <property name="RequestedPresence" type="(uss)" access="readwrite"
-      tp:type="Account_Presence">
+      tp:type="Simple_Presence">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The requested presence for this account. When this is changed, the
           account manager should attempt to manipulate the connection manager
diff --git a/spec/Channel_Interface_Delivery_Reporting.xml b/spec/Channel_Interface_Delivery_Reporting.xml
index 29b0f769b..8d6f79784 100644
--- a/spec/Channel_Interface_Delivery_Reporting.xml
+++ b/spec/Channel_Interface_Delivery_Reporting.xml
@@ -249,7 +249,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </dl>
     </tp:docstring>
 
-    <tp:enum name="Delivery_Status" value-prefix="Delivery_Status">
+    <tp:enum name="Delivery_Status" value-prefix="Delivery_Status" type="u">
       <tp:docstring>
         <p>The status of a message as indicated by a delivery report.</p>
 
@@ -304,7 +304,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     </tp:enum>
 
     <tp:flags name="Delivery_Reporting_Support_Flags"
-      value-prefix="Delivery_Reporting_Support_Flag">
+      value-prefix="Delivery_Reporting_Support_Flag" type="u">
       <tp:docstring>
         Flags indicating the level of support for delivery reporting on this
         channel. Any future flags added to this set will conform to the
diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml
index 64416c2bc..cab68c5cd 100644
--- a/spec/Channel_Interface_Group.xml
+++ b/spec/Channel_Interface_Group.xml
@@ -192,9 +192,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:flag suffix="Handle_Owners_Not_Available" value="1024">
         <tp:docstring>
           In rooms with channel specific handles (ie Channel_Specific_Handles
-          flag is set), this flag indicates that none of the handle owners are
-          available, and that GetHandleOwners method will always return 0 for
-          channel members other than the self handle.
+          flag is set), this flag indicates that no handle owners are
+          available, apart from the owner of the SelfHandle.
+
+          <tp:rationale>
+            This used to be an important optimization to avoid repeated
+            GetHandleOwners calls, before we introduced the HandleOwner
+            property and HandleOwnerChanged signal.
+          </tp:rationale>
         </tp:docstring>
       </tp:flag>
       <tp:flag suffix="Properties" value="2048">
diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml
index 6e64e3a63..8c5c33bba 100644
--- a/spec/Channel_Interface_Hold.xml
+++ b/spec/Channel_Interface_Hold.xml
@@ -65,15 +65,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         another process.
       </tp:docstring>
 
-      <arg name="HoldState" direction="out" type="u"
-          tp:type="Local_Hold_State">
+      <arg name="HoldState" type="u" tp:type="Local_Hold_State">
         <tp:docstring>
           The state of the channel
         </tp:docstring>
       </arg>
 
-      <arg name="Reason" direction="out" type="u"
-          tp:type="Local_Hold_State_Reason">
+      <arg name="Reason" type="u" tp:type="Local_Hold_State_Reason">
         <tp:docstring>
           The reason for the state change
         </tp:docstring>
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index 677ca09fe..7ba2f8e9f 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -81,7 +81,7 @@ USA.</p>
     </property>
 
     <tp:flags name="Message_Part_Support_Flags"
-      value-prefix="Message_Part_Support_Flag">
+      value-prefix="Message_Part_Support_Flag" type="u">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Flags indicating the level of support for message parts on this
           channel. They are designed such that setting more flags always
@@ -471,7 +471,8 @@ USA.</p>
       </tp:possible-errors>
     </method>
 
-    <tp:flags name="Message_Sending_Flags" value-prefix="Message_Sending_Flag">
+    <tp:flags name="Message_Sending_Flags" value-prefix="Message_Sending_Flag"
+      type="u">
       <tp:docstring>
         Flags altering the way a message is sent. The "most usual" action
         should always be to have these flags unset.
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index b3265ec50..049ed6b8d 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -457,7 +457,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
       <p>On protocols where a conversation with a user is actually just
         a nameless chat room starting with exactly two members, to which
-        more members can be invited, calling RequestChannel with type Text
+        more members can be invited, calling
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref>
+        with type Text
         and handle type CONTACT should continue to succeed, but may return
         a channel with handle type 0, handle 0, the group interface,
         and the local and remote contacts in its members.</p>
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 792499671..b350f140e 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -73,12 +73,39 @@ USA.</p>
         </tp:docstring>
       </arg>
 
-      <tp:docstring>
-        Get the optional interfaces supported by this connection.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Get the optional interfaces supported by this connection.
+          Before the connection status changes to CONNECTED, the return
+          from this method may change at any time, but it is guaranteed that
+          interfaces will only be added, not removed. After the connection
+          status changes to CONNECTED, the return from this method cannot
+          change further.</p>
+
+        <p>There is no explicit change notification; reasonable behaviour
+          for a client would be to retrieve the interfaces list once
+          initially, and once more when it becomes CONNECTED.</p>
+
+        <tp:rationale>
+          <p>In some connection managers, certain capabilities of a connection
+            are known to be implemented for all connections (e.g. support
+            for SimplePresence), and some interfaces (like SimplePresence) can
+            even be used before connecting. Other capabilities may
+            or may not exist, depending on server functionality; by the time
+            the connection goes CONNECTED, the connection manager is expected
+            to have evaluated the server's functionality and enabled any extra
+            interfaces for the remainder of the Connection's lifetime.</p>
+        </tp:rationale>
       </tp:docstring>
 
       <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected">
+          <tp:docstring>
+             Before version 0.17.UNRELEASED calling GetInterfaces while
+             on a connection that is not yet CONNECTED wasn't allowed. If a
+             CM returns this error, its list of interfaces should be regarded
+             as empty until it becomes CONNECTED.
+          </tp:docstring>
+        </tp:error>
       </tp:possible-errors>
     </method>
 
@@ -294,13 +321,19 @@ USA.</p>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
-          The handle type is invalid
+          <tp:docstring>
+            The handle type is invalid
+          </tp:docstring>
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
-          One of the given handles is not valid
+          <tp:docstring>
+            One of the given handles is not valid
+          </tp:docstring>
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
-          One of the given handles is not held by this client
+          <tp:docstring>
+            One of the given handles is not held by this client
+          </tp:docstring>
         </tp:error>
       </tp:possible-errors>
     </method>
@@ -483,10 +516,14 @@ USA.</p>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
-          The handle type is invalid
+          <tp:docstring>
+            The handle type is invalid
+          </tp:docstring>
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
-          The given name is not a valid entity of the given type
+          <tp:docstring>
+            The given name is not a valid entity of the given type
+          </tp:docstring>
         </tp:error>
       </tp:possible-errors>
     </method>
diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml
index e4b739d23..3e84c6b7b 100644
--- a/spec/Connection_Interface_Capabilities.xml
+++ b/spec/Connection_Interface_Capabilities.xml
@@ -28,16 +28,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         manager that it will ordinarily be able to create a channel when given
         a request with the given type and handle.</p>
 
-      <p>Capabilities can pertain to a certain contact handle, representing
-        activities such as having a text chat or a voice call with the user, or
-        can be on the connection itself (where the handle will be zero), where
-        they represent the ability to create channels for chat rooms or
-        activities such as searching and room listing. The activities are
-        represented by the D-Bus interface name of the channel type for that
-        activity.</p>
+      <p>Capabilities pertain to particular contact handles, and represent
+        activities such as having a text chat or a voice call with the user.
+        The activities are represented by the D-Bus interface name of the
+        channel type for that activity.</p>
 
       <p>The generic capability flags are defined by
-        Connection_Capability_Flags.</p>
+        <tp:type>Connection_Capability_Flags</tp:type>.</p>
 
       <p>In addition, channel types may have type specific capability flags of
         their own, which are described in the documentation for each channel
@@ -50,6 +47,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         to them which are implemented by available client processes.</p>
     </tp:docstring>
 
+    <tp:changed version="0.17.UNRELEASED">Previously, this interface
+      also expressed capabilities of the connection itself, indicating what
+      sorts of channels could be requested (for instance, the ability to
+      open chatroom lists or chatrooms). However, this was never very
+      well-defined or consistent, and as far as we know it was never
+      implemented correctly. This usage is now deprecated.</tp:changed>
+
+    <!-- FIXME: are the type-specific flags sufficient, in a world that has
+    the Requests interface? It'd be nice if we could advertise capabilities
+    that are not defined in terms of a channel type but rather in terms of
+    a property or something, e.g. Channel.Interface.TLS.Secure for
+    individually TLS'd channels. -->
+
     <tp:flags name="Connection_Capability_Flags"
       value-prefix="Connection_Capability_Flag" type="u">
       <tp:flag suffix="Create" value="1">
@@ -136,7 +146,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
         <p>Upon a successful invocation of this method, the CapabilitiesChanged
         signal will be emitted for the user's own handle (as returned by
-        GetSelfHandle) the by the connection manager to indicate the changes
+        GetSelfHandle) by the connection manager to indicate the changes
         that have been made.  This signal should also be monitored to ensure
         that the set is kept accurate - for example, a client may remove
         capabilities or type specific capability flags when it exits
@@ -162,20 +172,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           </ul>
         </tp:docstring>
       </arg>
-      <tp:docstring>
-        Announce that there has been a change of capabilities on the
-        given handle, or on the connection itself if the handle is zero.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Announce that there has been a change of capabilities on the
+          given handle.</p>
+
+        <p>If the handle is zero, the capabilities refer to the connection
+          itself, in some poorly defined way. This usage is deprecated and
+          clients should ignore it.</p>
       </tp:docstring>
     </signal>
 
     <method name="GetCapabilities">
       <arg direction="in" name="handles" type="au" tp:type="Contact_Handle[]">
-        <tp:docstring>
-          An array of contact handles for this connection, or zero to query capabilities available on the connection itself
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>An array of contact handles for this connection.</p>
+
+          <p>This may include zero, which originally meant a query for
+            capabilities available on the connection itself. This usage
+            is deprecated; clients SHOULD NOT do this, and connection managers
+            SHOULD proceed as though zero had not been present in this
+            list.</p>
         </tp:docstring>
       </arg>
       <arg direction="out" type="a(usuu)" tp:type="Contact_Capability[]">
-        <tp:docstring>
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           An array of structures containing:
           <ul>
             <li>an integer handle representing the contact</li>
@@ -186,15 +206,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:docstring>
       </arg>
       <tp:docstring>
-        Returns an array of capabilities for the given contact handles, or
-        the connection itself (where handle is zero).
+        Returns an array of capabilities for the given contact handles.
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
           <tp:docstring>
-            The handle does not represent a contact
+            The handle does not represent a contact and is not zero
           </tp:docstring>
         </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml
index 9527b6143..489ac238a 100644
--- a/spec/Connection_Interface_Presence.xml
+++ b/spec/Connection_Interface_Presence.xml
@@ -258,10 +258,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:possible-errors>
     </method>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>This interface is for services which have a concept of presence which can
-    be published for yourself and monitored on your contacts. Telepathy's
-    definition of presence is based on that used by the Galago project
-    (see http://www.galago-project.org/).</p>
+      <p>This interface will become deprecated in future versions. New
+        client implementations MAY use
+        org.freedesktop.Telepathy.Connection.Interface.SimplePresence
+        instead; new connection managers SHOULD implement both
+        Presence and SimplePresence.</p>
+
+      <p>This interface is for services which have a concept of presence which
+        can be published for yourself and monitored on your contacts.
+        Telepathy's definition of presence is based on that used by
+        <a href="http://www.galago-project.org/">the Galago
+          project</a>.</p>
 
     <p>Presence on an individual (yourself or one of your contacts) is modelled as
     a last activity time along with a set of zero or more statuses, each of
@@ -276,14 +283,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     choices:</p>
 
     <ul>
-      <li>available</li>
-      <li>away</li>
-      <li>brb (Be Right Back)</li>
-      <li>busy</li>
-      <li>dnd (Do Not Disturb),</li>
-      <li>xa (Extended Away)</li>
-      <li>hidden (aka Invisible)</li>
-      <li>offline</li>
+      <li>available (corresponding to Connection_Presence_Type_Available)</li>
+      <li>away (corresponding to Connection_Presence_Type_Away)</li>
+      <li>brb (Be Right Back) (corresponding to
+        Connection_Presence_Type_Away, but more specific)</li>
+      <li>busy (corresponding to Connection_Presence_Type_Busy)</li>
+      <li>dnd (Do Not Disturb) (corresponding to
+        Connection_Presence_Type_Busy, but more specific)</li>
+      <li>xa (Extended Away) (corresponding to
+        Connection_Presence_Type_Extended_Away)</li>
+      <li>hidden (aka Invisible) (corresponding to
+        Connection_Presence_Type_Hidden)</li>
+      <li>offline (corresponding to Connection_Presence_Type_Offline)</li>
+      <li>unknown (corresponding to Connection_Presence_Type_Unknown)</li>
+      <li>error (corresponding to Connection_Presence_Type_Error)</li>
     </ul>
 
     <p>As well as these well-known status identifiers, every status also has a
@@ -317,7 +330,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     <tp:enum name="Connection_Presence_Type" type="u">
       <tp:enumvalue suffix="Unset" value="0">
         <tp:docstring>
-          An invalid presence type used as a null value
+          An invalid presence type used as a null value. This value MUST NOT
+          appear in the result of GetStatuses, or in the Statuses property
+          of the SimplePresence interface.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Offline" value="1">
@@ -352,15 +367,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Unknown" value="7">
-        <tp:added version="0.17.unreleased"/>
+        <tp:added version="0.17.UNRELEASED"/>
         <tp:docstring>
-          Unknown, unable to determine presence.
+          Unknown, unable to determine presence for this contact, for example
+          if the protocol only allows presence of subscribed contacts.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Error" value="8">
-        <tp:added version="0.17.unreleased"/>
+        <tp:added version="0.17.UNRELEASED"/>
         <tp:docstring>
-          Error, error while trying to determine presence.
+          Error, an error occurred while trying to determine presence.  The
+          message, if set, is an error from the server.
         </tp:docstring>
       </tp:enumvalue>
     </tp:enum>
diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml
index 2a3df157e..56ac9d384 100644
--- a/spec/Connection_Interface_Simple_Presence.xml
+++ b/spec/Connection_Interface_Simple_Presence.xml
@@ -1,29 +1,24 @@
 <?xml version="1.0" ?>
 <node name="/Connection_Interface_Simple_Presence" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>
-    Copyright (C) 2005-2008 Collabora Limited
-  </tp:copyright>
-  <tp:copyright>
-Copyright (C) 2005, 2006 Nokia Corporation
-  </tp:copyright>
-  <tp:copyright>
-Copyright (C) 2006 INdT
-  </tp:copyright>
+  <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">
-    <p>This library is free software; you can redistribute it and/or
-modify it under the terms of the GNU Lesser General Public
-License as published by the Free Software Foundation; either
-version 2.1 of the License, or (at your option) any later version.</p>
-
-<p>This library is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-Lesser General Public License for more details.</p>
-
-<p>You should have received a copy of the GNU Lesser General Public
-License along with this library; if not, write to the Free Software
-Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+    <p>This library is free software; you can redistribute it and/or modify it
+      under the terms of the GNU Lesser General Public License as published by
+      the Free Software Foundation; either version 2.1 of the License, or (at
+      your option) any later version.</p>
+
+    <p>This library is distributed in the hope that it will be useful, but
+      WITHOUT ANY WARRANTY; without even the implied warranty of
+      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser
+      General Public License for more details.</p>
+
+    <p>You should have received a copy of the GNU Lesser General Public License
+      along with this library; if not, write to the Free Software Foundation,
+      Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
   </tp:license>
+
   <interface name="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
 
@@ -31,122 +26,250 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <tp:docstring>
         A struct representing the presence of a contact.
       </tp:docstring>
+      <tp:member type="u" tp:type="Connection_Presence_Type" name="Type">
+        <tp:docstring>
+          The presence type, e.g. Connection_Presence_Type_Away.
+        </tp:docstring>
+      </tp:member>
       <tp:member type="s" name="Status">
-        <tp:docstring> Status </tp:docstring>
+        <tp:docstring>
+          The string identifier of the status, e.g. "brb", as defined in the
+          <tp:member-ref>Statuses</tp:member-ref> property.
+        </tp:docstring>
       </tp:member>
       <tp:member type="s" name="Status_Message">
-        <tp:docstring>
-          Status message. User interfaces should regard "" as unset
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The user-defined status message, e.g. "Back soon!".</p>
+
+          <p>Clients SHOULD set the status message for the local
+            user to the empty string, unless the user has actually provided
+            a specific message (i.e. one that conveys more information than the
+            Status).</p>
+
+          <p>User interfaces SHOULD regard an empty status message as unset,
+            and MAY replace it with a localized string corresponding to the
+            Status or Type.</p>
+
+          <tp:rationale>
+            Use case: Daf sets his status in Empathy by choosing the Welsh
+            translation of "Available" from a menu.
+            It is more informative for his English-speaking colleagues
+            to see the English translation of "Available" (as localized
+            by their own clients) than to see the Welsh version (which they
+            don't understand anyway).
+          </tp:rationale>
         </tp:docstring>
       </tp:member>
     </tp:struct>
 
     <tp:mapping name="Simple_Contact_Presences">
-      <tp:docstring>Mapping returned by GetPresences and signalled by
-        PresencesChanged, where the keys are contacts and the values represent
-        their presence.</tp:docstring>
-      <tp:member type="u" tp:type="Contact_Handle" name="Contact"/>
-      <tp:member type="(ss)" tp:type="Simple_Presence" name="Presence"/>
+      <tp:docstring>
+        Mapping returned by <tp:member-ref>GetPresences</tp:member-ref>
+        and signalled by <tp:member-ref>PresencesChanged</tp:member-ref>,
+        indicating the presence of a number of contacts.
+      </tp:docstring>
+      <tp:member type="u" tp:type="Contact_Handle" name="Contact">
+        <tp:docstring>
+          A contact
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="(uss)" tp:type="Simple_Presence" name="Presence">
+        <tp:docstring>
+          The contact's presence
+        </tp:docstring>
+      </tp:member>
     </tp:mapping>
 
     <tp:struct name="Simple_Status_Spec">
       <tp:docstring>
         A struct containing information about a status.
       </tp:docstring>
-      <tp:member type="u" tp:type="Simple_Connection_Presence_Type"
-        name="Type">
+      <tp:member type="u" tp:type="Connection_Presence_Type" name="Type">
         <tp:docstring>
-          The type of a presence. If the status identifier is unknown to a
-          client, this value should be used a hint.
+          The type of a presence. This SHOULD NOT be used as a way to set
+          statuses that the client does not recognise (as explained in
+          <tp:member-ref>SetPresence</tp:member-ref>), but MAY be used to check
+          that the client's assumptions about a particular status name
+          match the connection manager's.
         </tp:docstring>
       </tp:member>
       <tp:member type="b" name="May_Set_On_Self">
         <tp:docstring>
-          Whether or not this status may be set on the connection using
-          SetPresence.
+          If true, the user can set this status on themselves using
+          <tp:member-ref>SetPresence</tp:member-ref>.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="b" name="Can_Have_Message">
+        <tp:docstring>
+          If true, a non-empty message can be set for this status. Otherwise,
+          the empty string is the only acceptable message.
+
+          <tp:rationale>
+            On IRC you can be Away with a status message, but if you are
+            available you cannot set a status message.
+          </tp:rationale>
         </tp:docstring>
       </tp:member>
     </tp:struct>
 
     <tp:mapping name="Simple_Status_Spec_Map">
+      <tp:docstring>
+        A mapping describing possible statuses.
+      </tp:docstring>
+
       <tp:member type="s" name="Identifier">
         <tp:docstring>
-          The string identifier of this status
+          The string identifier of this status.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="(ubb)" tp:type="Simple_Status_Spec" name="Spec">
+        <tp:docstring>
+          Details of this status.
         </tp:docstring>
       </tp:member>
-      <tp:member type="(ub)" tp:type="Simple_Status_Spec" name="Spec"/>
     </tp:mapping>
 
     <method name="SetPresence">
       <arg direction="in" name="status" type="s">
-        <tp:docstring>
-          The string identifier of the desired status
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The string identifier of the desired status. Possible status
+            identifiers are defined in the
+            <tp:member-ref>Statuses</tp:member-ref> property.</p>
+
+          <p>Clients MUST NOT set a status whose string value they do not
+            recognise, even if its presence type in Statuses
+            matches what the user requested.</p>
+
+          <tp:rationale>
+            <p>Suppose a protocol has statuses that include 'phone' (of type
+              BUSY) and 'in-a-meeting' (of type BUSY), but there is no
+              generic 'busy' status.</p>
+
+            <p>If the user requests "Busy" status from a menu, a
+              client author might be tempted to pick an arbitrary status
+              that has type BUSY. However, on this protocol, neither of
+              the choices would be appropriate, and incorrect information
+              about the user would be conveyed.</p>
+          </tp:rationale>
         </tp:docstring>
       </arg>
       <arg direction="in" name="status_message" type="s">
         <tp:docstring>
-          The status message associated with the current status
+          The status message associated with the current status.
         </tp:docstring>
       </arg>
-      <tp:docstring>
-        Request that the presence status and status message are published for
-        the connection.  Changes will be indicated by PresencesChanged signals
-        being emitted. On certain protocols, this method may be called on a
-        newly-created connection which is still in the DISCONNECTED state, and
-        will sign on with the requested status. In DISCONNECTED state the
-        Statuses property will indicate which statuses are allowed to be set
-        while DISCONNECTED (none if the Connection Manager doesn't allow this),
-        this value should not be cached as the set of allowed presences might
-        change upon connecting.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Request that the presence status and status message are published for
+          the connection.  Changes will be indicated by
+          <tp:member-ref>PresencesChanged</tp:member-ref>
+          signals being emitted.</p>
+
+        <p>This method may be called on a newly-created connection while it
+          is still in the DISCONNECTED state, to request that when the
+          connection connects, it will do so with the selected status.</p>
+
+        <p>In DISCONNECTED state the
+          <tp:member-ref>Statuses</tp:member-ref>
+          property will indicate which statuses are allowed to be set
+          while DISCONNECTED (none, if the Connection Manager doesn't allow
+          this). This value MUST NOT be cached, as the set of allowed
+          presences might change upon connecting.</p>
       </tp:docstring>
       <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            Either the specified status is not supported, the specified
+            status cannot be set on the user themselves, or a non-empty
+            message was supplied for a status that does not
+            accept a message.
+          </tp:docstring>
+        </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
       </tp:possible-errors>
     </method>
+
     <method name="GetPresences">
       <arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
         <tp:docstring>
-          An array of the contacts whose presence should be obtained
+          An array of the contacts whose presence should be obtained.
         </tp:docstring>
       </arg>
-      <arg direction="out" name="presence" type="a{u(ss)}"
+      <arg direction="out" name="presence" type="a{u(uss)}"
         tp:type="Simple_Contact_Presences">
-        <tp:docstring>
-          Presence information in the same format as for the PresencesChanged
-          signal
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Presence information in the same format as for the
+            <tp:member-ref>PresencesChanged</tp:member-ref> signal.
+            The returned mapping MUST include an entry for each contact
+            in the method's argument.</p>
+
+          <p>The definition of the connection presence types Unknown
+            and Offline means that if a connection manager will return
+            Unknown for contacts not on the subscribe list, it MUST delay
+            the reply to this method call until it has found out which
+            contacts are, in fact, on the subscribe list.</p>
         </tp:docstring>
       </arg>
       <tp:docstring>
         Get presence previously emitted by PresencesChanged for the given
         contacts. Data is returned in the same structure as the
-        PresencesChanged signal.
+        PresencesChanged signal; no additional network requests are made.
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError">
+          <tp:docstring>
+            While discovering the subscribe list in order to distinguish
+            between Unknown and Offline statuses, a network error occurred.
+          </tp:docstring>
+        </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
       </tp:possible-errors>
     </method>
 
     <property name="Statuses" access="read"
-      type="a{s(ub)}" tp:type="Status_Spec_Map">
-      <tp:docstring>
-        A dictionary of the valid presence statuses for this connection. While
-        DISCONNECTED it contains the set of presence statuses allowed to be set
-        before connecting, which should not be cached as the value is can
-        change when CONNECTED. When CONNECTED it contains the presence
-        statuses available on this protocol.
+      type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A dictionary where the keys are the presence statuses that the user
+          can set on themselves for this connection, and the values are the
+          corresponding presence types.</p>
+
+        <p>While the connection is in the DISCONNECTED state, it contains
+          the set of presence statuses allowed to be set before connecting.
+          The connection manager will attempt to set the appropriate status
+          when the connection becomes connected, but cannot necessarily
+          guarantee it. The available statuses cannot change until the
+          connection status changes, so there is no change notification.</p>
+
+        <p>While the connection is in the CONNECTED state, this property
+          contains the set of presence statuses which are actually available
+          on this protocol. This set is constant for the remaining lifetime
+          of the connection, so again, there is no change notification.</p>
+
+        <p>While the connection is in the CONNECTING state, the value of
+          this property is undefined and SHOULD NOT be used. It can change
+          at any time without notification (in particular, any cached values
+          from when the connection was in the DISCONNECTED or CONNECTING
+          state MUST NOT be assumed to still be correct when the state has
+          become CONNECTED).</p>
+
+        <p>This property MUST include the special statuses "unknown" and
+          "error" if and only if the connection manager can emit them
+          as a contact's status.</p>
+
+        <tp:rationale>
+          For instance, connection managers for local-xmpp (XEP-0174) would
+          omit "unknown" since there is no such concept.
+        </tp:rationale>
       </tp:docstring>
     </property>
 
     <signal name="PresencesChanged">
-      <arg name="presence" type="a{u(ss)}" tp:type="Contact_Presences">
+      <arg name="presence" type="a{u(uss)}" tp:type="Simple_Contact_Presences">
         <tp:docstring>
-        A dictionary of contact handles mapped to the status and status message
+          A dictionary of contact handles mapped to the status,
+          presence type and status message.
         </tp:docstring>
       </arg>
       <tp:docstring>
@@ -157,107 +280,103 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     </signal>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>This interface is for services which have a concept of presence which can
-    be published for yourself and monitored on your contacts. Telepathy's
-    definition of presence is based on that used by the Galago project
-    (see http://www.galago-project.org/).</p>
-
-    <p>Presence on an individual (yourself or one of your contacts) is modelled as
-    a status and a status message. Valid statuses are defined per connection,
-    and a list of them can be obtained from the Statuses property.</p>
-
-    <p>Each status has an arbitrary string identifier which should have an agreed
-    meaning between the connection manager and any client which is expected to
-    make use of it. The following well-known values (in common with those in
-    Galago) should be used where possible to allow clients to identify common
-    choices:</p>
-
-    <ul>
-      <li>available</li>
-      <li>away</li>
-      <li>brb (Be Right Back)</li>
-      <li>busy</li>
-      <li>dnd (Do Not Disturb),</li>
-      <li>xa (Extended Away)</li>
-      <li>hidden (aka Invisible)</li>
-      <li>offline</li>
-    </ul>
-
-    <p>As well as these well-known status identifiers, every status also has a
-    numerical type value chosen from SimpleConnectionPresenceType which can be
-    used by the client to classify even unknown statuses into different
-    fundamental types.</p>
-
-    <p>These numerical types exist so that even if a client does not understand
-    the string identifier being used, and hence cannot present the presence to
-    the user to set on themselves, it may display an approximation of the
-    presence if it is set on a contact.</p>
-
-    <p>Apart from these status indentifiers there are two special ones that
-    may be present. 'unknown' with type Unknown and 'error' with type
-    Error. 'unknown' indicates that it is impossible to determine the presence
-    of a contact at this time, for example because it's not on the 'subscibe'
-    list and the protocol only allows one to determine the presence of contacts
-    you're subscribed to. 'error' indicates that there was a failure in
-    determining the status of a contact. </p>
-
-    <p>If the connection has a 'subscribe' contact list, PresencesChanged
-    signals should be emitted to indicate changes of contacts on this list, and
-    should also be emitted for changes in your own presence. Depending on the
-    protocol, the signal may also be emitted for others such as people with
-    whom you are communicating, and any user interface should be updated
-    accordingly.</p>
+      <p>This interface is for services which have a concept of presence which
+        can be published for yourself and monitored on your contacts.</p>
+
+      <p>Presence on an individual (yourself or one of your contacts) is
+        modelled as a status and a status message. Valid statuses are defined
+        per connection, and a list of those that can be set on youself
+        can be obtained from the
+        <tp:member-ref>Statuses</tp:member-ref>
+        property.</p>
+
+      <p>Each status has an arbitrary string identifier which should have an
+        agreed meaning between the connection manager and any client which is
+        expected to make use of it. The following well-known values should be
+        used where possible to allow clients to identify common choices:</p>
+
+      <table>
+        <tr>
+          <th>status identifier</th>
+          <th>Connection_Presence_Type</th>
+          <th>comments</th>
+        </tr>
+        <tr>
+          <td>available</td>
+          <td>Connection_Presence_Type_Available</td>
+          <td></td>
+        </tr>
+        <tr>
+          <td>away</td>
+          <td>Connection_Presence_Type_Away</td>
+          <td></td>
+        </tr>
+        <tr>
+          <td>brb</td>
+          <td>Connection_Presence_Type_Away</td>
+          <td>Be Right Back (a more specific form of Away)</td>
+        </tr>
+        <tr>
+          <td>busy</td>
+          <td>Connection_Presence_Type_Busy</td>
+          <td></td>
+        </tr>
+        <tr><td>dnd</td>
+          <td>Connection_Presence_Type_Busy</td>
+          <td>Do Not Disturb (a more specific form of Busy)</td>
+        </tr>
+        <tr>
+          <td>xa</td>
+          <td>Connection_Presence_Type_Extended_Away</td>
+          <td>Extended Away</td>
+        </tr>
+        <tr>
+          <td>hidden</td>
+          <td>Connection_Presence_Type_Hidden</td>
+          <td>Also known as "Invisible" or "Appear Offline"</td>
+        </tr>
+        <tr>
+          <td>offline</td>
+          <td>Connection_Presence_Type_Offline</td>
+          <td></td>
+        </tr>
+        <tr>
+          <td>unknown</td>
+          <td>Connection_Presence_Type_Unknown</td>
+          <td>special, see below</td>
+        </tr>
+        <tr>
+          <td>error</td>
+          <td>Connection_Presence_Type_Error</td>
+          <td>special, see below</td>
+        </tr>
+      </table>
 
+      <p>As well as these well-known status identifiers, every status also has
+        a numerical type value chosen from ConnectionPresenceType which can be
+        used by the client to classify even unknown statuses into different
+        fundamental types.</p>
+
+      <p>These numerical types exist so that even if a client does not
+        understand the string identifier being used, and hence cannot present
+        the presence to the user to set on themselves, it may display an
+        approximation of the presence if it is set on a contact.</p>
+
+      <p>As well as the normal status identifiers, there are two special ones
+        that may be present: 'unknown' with type Unknown and 'error' with type
+        Error. 'unknown' indicates that it is impossible to determine the
+        presence of a contact at this time, for example because it's not on the
+        'subscribe' list and the protocol only allows one to determine the
+        presence of contacts you're subscribed to. 'error' indicates that there
+        was a failure in determining the status of a contact.</p>
+
+      <p>If the connection has a 'subscribe' contact list, PresencesChanged
+        signals should be emitted to indicate changes of contacts on this list,
+        and should also be emitted for changes in your own presence. Depending
+        on the protocol, the signal may also be emitted for others such as
+        people with whom you are communicating, and any user interface should
+        be updated accordingly.</p>
     </tp:docstring>
-    <tp:enum name="Simple_Connection_Presence_Type" type="u">
-      <tp:enumvalue suffix="Unset" value="0">
-        <tp:docstring>
-          An invalid presence type used as a null value
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Offline" value="1">
-        <tp:docstring>
-          Offline
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Available" value="2">
-        <tp:docstring>
-          Available
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Away" value="3">
-        <tp:docstring>
-          Away
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Extended_Away" value="4">
-        <tp:docstring>
-          Away for an extended time
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Hidden" value="5">
-        <tp:docstring>
-          Hidden (invisible)
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Busy" value="6">
-        <tp:docstring>
-          Busy, Do Not Disturb.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Unknown" value="7">
-        <tp:added version="0.17.unrelease"/>
-        <tp:docstring>
-          Unknown, unable to determine presence.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Error" value="8">
-        <tp:added version="0.17.unreleased"/>
-        <tp:docstring>
-          Error, error while trying to determine presence.
-        </tp:docstring>
-      </tp:enumvalue>
-    </tp:enum>
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index d16960727..760e57476 100644
--- a/spec/Connection_Manager.xml
+++ b/spec/Connection_Manager.xml
@@ -21,13 +21,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   <interface name="org.freedesktop.Telepathy.ConnectionManager">
 
     <tp:simple-type name="Connection_Manager_Name" type="s">
-      <tp:docstring>
-        The name of a connection manager, found in its well-known
-        bus name and object path. This must be a non-empty string of
-        ASCII letters, digits and underscores, starting with a letter.
-        This is typically the name of the executable with any "telepathy-"
-        prefix removed, and any hyphen/minus signs replaced by
-        underscores.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The name of a connection manager, found in its well-known
+          bus name and object path. This must be a non-empty string of
+          ASCII letters, digits and underscores, starting with a letter.
+          This is typically the name of the executable with any "telepathy-"
+          prefix removed, and any hyphen/minus signs replaced by
+          underscores.</p>
+
+        <p>Connection manager names SHOULD NOT be the same as the name of
+          the protocol they implement.</p>
+
+        <tp:rationale>
+          <p>This is likely to lead to conflicts between different
+            implementations of the same protocol (or indeed inability
+            to distinguish between the different implementations!). The
+            Telepathy project traditionally uses some sort of pun (Haze is
+            based on libpurple, Salut implements a protocol often called
+            Bonjour, and Wilde implements the OSCAR protocol).</p>
+        </tp:rationale>
+
+        <p>Connection manager names SHOULD NOT be the same as the name of
+          a library on which they are based.</p>
+
+        <tp:rationale>
+          <p>We often abbreviate, for instance, telepathy-haze as "Haze",
+            but abbreviating telepathy-sofiasip to "Sofia-SIP" would cause
+            confusion between the connection manager and the library it
+            uses. Please don't repeat that mistake.</p>
+        </tp:rationale>
       </tp:docstring>
       <tp:changed version="0.17.1">Prior to version 0.17.1, the allowed
         characters were not specified</tp:changed>
@@ -298,6 +320,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:possible-errors>
     </method>
 
+    <property name="Interfaces" type="as" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A list of the extra interfaces provided by this connection manager
+          (i.e. extra functionality that can be provided even before a
+          connection has been created).</p>
+
+        <p>No interfaces suitable for listing in this property are currently
+          defined; it's provided as a hook for possible future
+          functionality.</p>
+
+        <p>To be compatible with older connection managers, if retrieving
+          this property fails, clients SHOULD assume that its value is
+          an empty list.</p>
+      </tp:docstring>
+      <tp:added version="0.17.UNRELEASED"/>
+    </property>
+
+    <!-- FIXME: One thing we could perhaps use Interfaces for would be a
+    ConnectionManager.Interface.Capabilities that can give hints regarding
+    the capabilities (in the sense of
+    Connection.Interface.Requests.AvailableChannelClasses and/or
+    Connection.GetInterfaces()) that a Connection from this CM is likely
+    to have -->
+
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
     <p>A D-Bus service which allows connections to be created. The manager
       processes are intended to be started by D-Bus service activation.</p>
diff --git a/spec/generic-types.xml b/spec/generic-types.xml
index a96237df0..c0a000d07 100644
--- a/spec/generic-types.xml
+++ b/spec/generic-types.xml
@@ -17,7 +17,11 @@
   </tp:simple-type>
 
   <tp:simple-type name="DBus_Interface" type="s">
-    <tp:docstring>A string representing a D-Bus interface</tp:docstring>
+    <tp:docstring>An ASCII string representing a D-Bus interface - two or more
+      elements separated by dots, where each element is a non-empty
+      string of ASCII letters, digits and underscores, not starting with
+      a digit. The maximum total length is 255 characters. For example,
+      "org.freedesktop.DBus.Peer".</tp:docstring>
   </tp:simple-type>
 
   <tp:simple-type name="DBus_Signature" type="s">
@@ -26,6 +30,35 @@
       with dbus-glib)</tp:docstring>
   </tp:simple-type>
 
+  <tp:simple-type name="DBus_Member" type="s">
+    <tp:docstring>An ASCII string representing a D-Bus method, signal
+      or property name - a non-empty string of ASCII letters, digits and
+      underscores, not starting with a digit, with a maximum length of 255
+      characters. For example, "Ping".</tp:docstring>
+  </tp:simple-type>
+
+  <tp:simple-type name="DBus_Qualified_Member" type="s">
+    <tp:docstring>A string representing the full name of a D-Bus method,
+      signal or property, consisting of a DBus_Interface, followed by
+      a dot, followed by a DBus_Member. For example,
+      "org.freedesktop.DBus.Peer.Ping".</tp:docstring>
+  </tp:simple-type>
+
+  <tp:mapping name="Qualified_Property_Value_Map">
+    <tp:docstring>A mapping from strings representing D-Bus
+      properties (by their namespaced names) to their values.</tp:docstring>
+    <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
+      <tp:docstring>
+        A D-Bus interface name, followed by a dot and a D-Bus property name.
+      </tp:docstring>
+    </tp:member>
+    <tp:member type="v" name="Value">
+      <tp:docstring>
+        The value of the property.
+      </tp:docstring>
+    </tp:member>
+  </tp:mapping>
+
   <tp:mapping name="String_Variant_Map">
     <tp:docstring>A mapping from strings to variants representing extra
       key-value pairs.</tp:docstring>