From c5e09cf82446ab4c7bb82626acc5cf1eafef0014 Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Mon, 30 Jan 2012 15:55:33 +0000
Subject: [PATCH] Add rationale for SupportedLocationFeatures, Can_Set

Taken from my earlier branch which added a separate CanSet boolean
property.
---
 spec/Connection_Interface_Location.xml |   33 ++++++++++++++++++++++++-------
 1 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml
index c4fd68c..49593fb 100644
--- a/spec/Connection_Interface_Location.xml
+++ b/spec/Connection_Interface_Location.xml
@@ -416,19 +416,36 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         type="u" tp:type="Location_Features" access="read">
       <tp:added version="0.19.6"/>
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        Indicates the Location features supported by this connection. This
-        property MAY be undefined before <tp:dbus-ref
-          namespace="org.freedesktop.Telepathy.Connection">Status</tp:dbus-ref>
-        becomes <code>Connected</code>, but MUST remain constant thereafter.
+        <p>Indicates the Location features supported by this connection. This
+          property MAY be undefined before <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection">Status</tp:dbus-ref>
+          becomes <code>Connected</code>, but MUST remain constant thereafter.</p>
+
+        <tp:rationale>
+          <p>On XMPP, you don't know what the server supports until you ask it.
+            The definition of this property implies that implementations using
+            XMPP will need to check whether the server supports PEP before moving
+            to the CONNECTED state.</p>
+        </tp:rationale>
       </tp:docstring>
     </property>
 
     <tp:flags name="Location_Features" type="u" value-prefix="Location_Feature">
       <tp:flag suffix="Can_Set" value="1">
-        <tp:docstring>
-          Indicates that setting your own location with
-          <tp:member-ref>SetLocation</tp:member-ref> is supported on this
-          connection.
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Indicates that setting your own location with
+            <tp:member-ref>SetLocation</tp:member-ref>
+            is supported on this connection.</p>
+
+          <tp:rationale>
+            <p>On XMPP, Location is advertised in a PEP node. If the user is
+              connected to a server that doesn't support PEP (like Google Talk),
+              they can't advertise their own location; however, the Location
+              interface should still appear in <tp:dbus-ref
+                namespace="org.freedesktop.Telepathy"
+                >Connection.Interfaces</tp:dbus-ref>, since the user can still
+              retrieve other contacts' locations.</p>
+          </tp:rationale>
         </tp:docstring>
       </tp:flag>
 
-- 
1.7.9.1