Ported to latest version MailNotification Spec

Major change is the property Capabilities renamed to MailNotificationFlags
and the prefix for MailNotificationFlags now being MAIL_NOTIFICATION_FLAG.
Other change are editorial changes.

Signed-off-by: Nicolas Dufresne <nicolas.dufresne@collabora.co.uk>

3 files changed, 376 insertions, 392 deletions

diff --git a/extensions/Connection_Interface_Mail_Notification.xml b/extensions/Connection_Interface_Mail_Notification.xml
index 7623cde54..91275456a 100644
--- a/extensions/Connection_Interface_Mail_Notification.xml
+++ b/extensions/Connection_Interface_Mail_Notification.xml
@@ -23,11 +23,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     tp:causes-havoc="experimental">
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
 
-    <tp:flags name="Mail_Notification_Flags" value-prefix="Mail_Notification" type="u" >
+    <tp:flags name="Mail_Notification_Flags" value-prefix="Mail_Notification_Flag" type="u" >
       <tp:flag suffix="Supports_Unread_Mail_Count" value="1">
         <tp:docstring>
-          The CM provides the number of unread e-mails (or e-mail
-          threads) in the main folder of your e-mail account set as
+          This Connection provides the number of unread e-mails (or e-mail
+          threads) in the main folder of your e-mail account, as the
           <tp:member-ref>UnreadMailCount</tp:member-ref> property. The
           connection manager will update this value by emitting the
           <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal.
@@ -35,91 +35,79 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:flag>
       <tp:flag suffix="Supports_Unread_Mails" value="2">
         <tp:docstring>
-          The CM provides a detailed list of unread e-mails set as
-          <tp:member-ref>UnreadMails</tp:member-ref> property. This flag
-          implies that <tt>Supports_Unread_Mail_Count</tt> is set and
-          CANNOT be combine with flag <tt>Emits_Mails_Received</tt>.
-          The CM will update the list by emitting the
+          This Connection provides a detailed list of unread e-mails, as the
+          <tp:member-ref>UnreadMails</tp:member-ref> property. If this flag
+          is set, <tt>Supports_Unread_Mail_Count</tt> MUST be set, and
+          <tt>Emits_Mails_Received</tt> MUST NOT be set.
+          The Connection will update the list by emitting the
           <tp:member-ref>UnreadMailsChanged</tp:member-ref> signals.
         </tp:docstring>
       </tp:flag>
       <tp:flag suffix="Emits_Mails_Received" value="4">
         <tp:docstring>
-          The CM emits <tp:member-ref>MailsReceived</tp:member-ref>
-          signal which provide details about newly arrived e-mails but does
-          NOT maintain their read/unread status afterward. This flag CANNOT
+          This Connection emits the <tp:member-ref>MailsReceived</tp:member-ref>
+          signal, which provides details about newly arrived e-mails but does
+          not maintain their read/unread status afterwards. This flag MUST NOT
           be combined with <tt>Supports_Unread_Mails</tt>.
         </tp:docstring>
       </tp:flag>
       <tp:flag suffix="Supports_Request_Inbox_URL" value="8">
         <tp:docstring>
-          The CM provides a URL (with optional POST data) that leads to the
-          the inbox folder of the e-mail account inside a web base client.
-          This URL can be obtained via the
-          <tp:member-ref>RequestInboxURL</tp:member-ref> method. It is
-          strongly advised to set this flag if
-          <tt>Supports_Unread_Mail_Count</tt> is set.
+          This Connection can provide a URL (with optional POST data) to
+          open the the inbox of the e-mail account in a web-based client, via
+          the <tp:member-ref>RequestInboxURL</tp:member-ref> method.
         </tp:docstring>
       </tp:flag>
       <tp:flag suffix="Supports_Request_Mail_URL" value="16">
-        <tp:docstring>
-          The CM provides a URL (with optional POST data) that leads to the
-          a specific mail inside a web base client. This URL can be obtained
-          via the <tp:member-ref>RequestMailURL</tp:member-ref> method. It is
-          strongly advised to set this flag if
-          <tt>Supports_Unread_Mails</tt> or <tt>Emits_Mails_Received</tt>
-          is set.
-          <tp:rationale>
-            If possible client SHOULD fallback to
-            <tp:member-ref>RequestInboxURL</tp:member-ref> if
-            <tt>Supports_Request_Mail_URL</tt> is NOT set.
-          </tp:rationale>
-        </tp:docstring>
-      </tp:flag>
-      <tp:flag suffix="Supports_Request_Compose_URL" value="32">
-        <tp:docstring>
-          The CM provides an URL (with optional POST data) that leads to a
-          e-mail editor inside a web base client. This URL can be obtained
-          via the <tp:member-ref>RequestComposeURL</tp:member-ref> method.
-          This flag is optional and does NOT depend on any other flags.
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>This Connection can provide a URL (with optional POST data) to open
+            a specific mail in a web-based client, via the
+            <tp:member-ref>RequestMailURL</tp:member-ref> method. This feature
+            is not useful unless either Emits_Mails_Received or
+            Supports_Unread_Mails is set.</p>
+
+          <p>If this flag is not set, clients SHOULD fall back to using
+            <tp:member-ref>RequestInboxURL</tp:member-ref> if available.</p>
         </tp:docstring>
       </tp:flag>
       <tp:docstring>
         <p>Flags representing capabilities provided by a connection manager.
-          Those values can be used as bitfield. Some flags depends or
-          conflicts with each others. While it's NOT mandatory, it is
-          strongly advised that <tt>Supports_Request_Inbox_URL</tt> flag is
-          set to ensure that there always exists a way to open unread
-          messages.</p>
+          Those values can be used as bitfield. Some flags depend on, or
+          conflict with, each other.</p>
+
+        <p>Connections SHOULD implement as many of these features as the
+          underlying protocol allows, preferring to implement
+          Supports_Unread_Mails instead of Emits_Mails_Received if both are
+          possible.</p>
       </tp:docstring>
     </tp:flags>
 
     <tp:enum name="HTTP_Method" type="u">
       <tp:enumvalue suffix="Get" value="0">
         <tp:docstring>
-          Use GET method when opening the URL.
+          Use the GET method when opening the URL.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Post" value="1">
         <tp:docstring>
-          Use POST method when opening the URL. Refer to
+          Use the POST method when opening the URL. Refer to
           <tp:type>HTTP_Post_Data</tp:type> for more details.
         </tp:docstring>
       </tp:enumvalue>
       <tp:docstring>
-        HTTP Method.
+        The HTTP Method with which to request a URL.
       </tp:docstring>
     </tp:enum>
 
     <tp:struct name="HTTP_Post_Data" array-name="HTTP_Post_Data_List">
-      <tp:docstring>
-        <p>A pair (key, value) representing POST data compatible with
-        application/x-www-form-urlencoded type. The strings MUST be
-        valid UTF-8 strings. The character set for the key MUST follow
-        the rules defined in
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A pair (key, value) representing POST data compatible with the
+        application/x-www-form-urlencoded MIME type. The strings MUST be
+        valid UTF-8 strings, and the characters used in the key MUST obey
+        the requirements of the
         <a href="http://www.w3.org/TR/html401/types.html#type-cdata">
-        W3 specification for CDATA</a>. The value SHOULD NOT be
-        encoded with HTML entity.</p>
+          HTML CDATA type</a>. The value MUST NOT be
+        encoded with HTML entities.</p>
 
         <p>For example, if the POST data should contain a key "less-than" with value
         "&lt;", and a key "percent" with value "%", this should be represented as
@@ -127,193 +115,231 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         resulting in a POST request whose request body is "less-than=&amp;lt;&amp;percent=%25".
         If a client passes this to a browser by writing it into an HTML form, it
         could do so by representing it as:</p>
-  
+
         <pre>
         &lt;input type="hidden" name="less-than"&gt;&amp;lt;&lt;/input&gt;
         &lt;input type="hidden" name="percent"&gt;%&lt;/input&gt;
         </pre>
 
         <tp:rationale>
-          This data MAY be used to generate a HTML file that will
-          automatically load the URL with appropriate POST data (in which case
-          the client MUST convert the
-          <a href="http://www.ietf.org/rfc/rfc1738.txt">reserved characters</a>
-          into HTML entities) or MAY use it as-is inside an UTF-8 API that will
-          instruct the browser how to load the URL (like the Netscape Plug-in
-          API). For this reason, the choice of non encoded UTF-8 strings is
-          prefered.
+          <p>This data can be used to generate a HTML file that will
+            automatically load the URL with appropriate POST data, in which case
+            the client MUST convert any characters that are special within HTML
+            into HTML entities. Alternatively, it can be used in an API that will
+            instruct the browser how to load the URL (like the Netscape Plug-in
+            API), in which case the client MUST escape
+            <a href="http://www.ietf.org/rfc/rfc1738.txt">characters that are
+              reserved in URLs</a>, if appropriate for that API.</p>
+
+          <p>An array of pairs is used instead of a map from keys to values,
+            because it's valid to repeat keys in both HTML and
+            x-www-form-urlencoded data.</p>
         </tp:rationale>
       </tp:docstring>
-      <tp:member type="s" name="Key"/>
-      <tp:member type="s" name="Value"/>
+      <tp:member type="s" name="Key">
+        <tp:docstring>The key, corresponding to a HTML control
+          name</tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="Value">
+        <tp:docstring>The value</tp:docstring>
+      </tp:member>
     </tp:struct>
 
     <tp:struct name="Mail_Address" array-name="Mail_Address_List">
       <tp:docstring>
-        A pair (name, address) representing an e-mail address 
-        (e.g. ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk") ).
+        A pair (name, address) representing an e-mail address,
+        such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk").
       </tp:docstring>
-      <tp:member type="s" name="Name"/>
-      <tp:member type="s" name="Address"/>
+      <tp:member type="s" name="Name">
+        <tp:docstring>The displayed name corresponding to the e-mail
+          address</tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="Address">
+        <tp:docstring>The actual e-mail address</tp:docstring>
+      </tp:member>
     </tp:struct>
 
+    <!-- FIXME: should this be Mail_Notification_Type? -->
     <tp:enum name="Mail_Type" type="u">
       <tp:enumvalue suffix="Single" value="0">
         <tp:docstring>
-          The e-mail is represented as a single message send by only
-          one sender.
+          The <tp:type>Mail</tp:type> represents a single message, sent by
+          a single sender.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Thread" value="1">
         <tp:docstring>
-          The e-mail refer to a thread where multiple person MAY
-          have replied.
+          The <tp:type>Mail</tp:type> represents a thread of e-mails, which
+          MAY have more than one sender.
         </tp:docstring>
       </tp:enumvalue>
       <tp:docstring>
-        E-mail representation type.
+        <p>The type of a mail notification.</p>
+
+        <tp:rationale>
+          <p>Google Talk notifies users about new mail in terms of unread
+            threads, rather than unread e-mails.</p>
+        </tp:rationale>
       </tp:docstring>
     </tp:enum>
 
     <tp:struct name="Mail_URL">
-      <tp:docstring>
-        Structure that contains required information to open Web base e-mail
-        UI without need for re-authentication.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A structure containing the required information to open a web-based
+          e-mail UI, without needing re-authentication (if possible).</p>
+
+        <p>Because the URL and POST data frequently contain short-lived
+          credential tokens, a new URL should be requested (by calling one of
+          the methods that returns a Mail_URL) for each visit to the web-based
+          UI, and the URL should be visited soon after it is returned.</p>
       </tp:docstring>
       <tp:member type="s" name="URL">
         <tp:docstring>
-          URL of the inbox folder or mail Web viewer.
+          The URL to which to send a request.
         </tp:docstring>
       </tp:member>
       <tp:member type="u" name="Method" tp:type="HTTP_Method">
         <tp:docstring>
-          HTTP Method for opening URL.
+          The HTTP method of the request.
         </tp:docstring>
       </tp:member>
       <tp:member type="a(ss)" name="Post_Data" tp:type="HTTP_Post_Data[]">
         <tp:docstring>
-          Array of name-value pair structs of the POST data to use when opening
-          the URL. Because the POST data frequently contains short-lived credential
-          tokens, this information MAY NOT be shared between clients.
+          An array of name-value pairs containing the POST data to use when
+          opening the URL. This MUST be an empty array if the Method is not
+          POST.
         </tp:docstring>
       </tp:member>
     </tp:struct>
 
-    <tp:simple-type name="Mail" type="a{sv}" array-name="Mail_List">
+    <tp:mapping name="Mail" array-name="Mail_List">
       <tp:docstring>
-        E-mail representation has been reduced to hash table with possible
-        keys (of type strings) listed above. Most keys are optional unless
-        explicity stated in dedicated section. At least one of "senders"
-        and "subject" key MUST be set.
-        <tp:rationale>
-          The hash map will allow extending the protocol without any ABI
-          changes. Only the documentation will need to be updated.
-        </tp:rationale>
+        An extensible map representing a mail or a thread of mails.
+        All keys are optional where not otherwise stated; however, at least
+        one of "senders" and "subject" must be included.
+      </tp:docstring>
 
-        <div class="indent">
-        <h3>Keys</h3>
-        <ul>
-          <li>id &#8212; s</li>
-          <div class="docstring">
+      <tp:member type="s" name="Key">
+        <tp:docstring>
+          <p>A key providing information about the mail or thread. Well-known
+            keys are as follows:</p>
+
+        <dl>
+          <dt>id &#8212; s</dt>
+          <dd>
             A unique ID for this e-mail. CMs with <tt>Supports_Unread_Mails</tt>
-            set in <tp:member-ref>Capabilities</tp:member-ref> MUST provide this
-            key in each <tp:type>Mail</tp:type>. The ID MUST be unique within the
-            session.
-          </div>
-
-          <li>type &#8212; u (<tp:type>Mail_Type</tp:type>)</li>
-          <div class="docstring">
-            Type of e-mail. This can be set to "single", which means e-mails
-            are represented separately, or "thread", when information is
-            described by the protocol as thread. Note that threads MAY have
-            multiple unread senders. If unset, "single" MUST be assumed.
-          </div>
-
-          <li>url-data &#8212; s</li>
-          <div class="docstring">An opaque string used to build URL when
-            calling <tp:member-ref>RequestMailURL</tp:member-ref>.
-          </div>
-
-          <li>senders &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</li>
-          <div class="docstring">
-            An array of sender display name and e-mail address pair. Note that
-            only e-mails thread MAY have multiple senders.
-          </div>
-
-          <li>to-addresses &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</li>
-          <div class="docstring">
-            An array of display name and e-mail address pair of
+            set in <tp:member-ref>MailNotificationFlags</tp:member-ref> MUST provide this
+            key in each <tp:type>Mail</tp:type>. If provided, the ID MUST be
+            unique within the lifetime of the Connection.
+          </dd>
+
+          <dt>type &#8212; u (<tp:type>Mail_Type</tp:type>)</dt>
+          <dd>
+            The type of notification. If omitted, Mail_Type_Single MAY be
+            assumed. For protocols where notifications are about threads
+            rather than individual mails, this MUST be set to Mail_Type_Thread.
+          </dd>
+
+          <dt>url-data &#8212; s</dt>
+          <dd>An opaque string provided to the Connection when
+            calling <tp:member-ref>RequestMailURL</tp:member-ref>,
+            containing information used by the Connection to build the URL.
+          </dd>
+
+          <dt>senders &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</dt>
+          <dd>
+            An array of sender display name and e-mail address pairs. Note that
+            only e-mails represented as a thread can have multiple senders.
+          </dd>
+
+          <dt>to-addresses &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</dt>
+          <dd>
+            An array of display name and e-mail address pairs representing
             the recipients.
-          </div>
-
-          <li>cc-addresses &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</li>
-          <div class="docstring">
-            An array of display name and e-mail address pair of the carbon
-            copy recipients.
-          </div>
-
-          <li>sent-timestamp &#8212; x (<tp:type>Unix_Timestamp64</tp:type>)</li>
-          <div class="docstring">A UNIX timestamp of when the message has been
-            sent (in seconds) (optional).
-          </div>
-
-          <li>received-timestamp &#8212; x (<tp:type>Unix_Timestamp64</tp:type>)</li>
-          <div class="docstring">A UNIX timestamp of when the message has been
-            received (in seconds).
-          </div>
-
-          <li>has-attachments &#8212; b</li>
-          <div class="docstring">A boolean of whether this message has
-            attachments.
-          </div>
-
-          <li>subject &#8212; s</li>
-          <div class="docstring">
-            The subject of the message. This must be encoded in UTF-8.
-          </div>
-
-          <li>content-type &#8212; s</li>
-          <div class="docstring">
-            MIME type of the message content. Two types are currently supported,
-            "text/plain" where text is valid UTF-8 and "text/html" where text
-            is a valid HTML document. "text/plain" MUST be assumed if unset.
-          </div>
-
-          <li>truncated &#8212; b</li>
-          <div class="docstring">
-            A boolean, TRUE means that the "content" contains only a snippet
-            of real body.
-          </div>
-
-          <li>content &#8212; s</li>
-          <div class="docstring">
-            The body of the message. The text MUST be formated according to
-            "content-type".
-          </div>
-
-          <li>folder &#8212; s</li>
-          <div class="docstring">
+          </dd>
+
+          <dt>cc-addresses &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</dt>
+          <dd>
+            An array of display name and e-mail address pairs representing
+            the carbon-copy recipients.
+          </dd>
+
+          <dt>sent-timestamp &#8212; x (<tp:type>Unix_Timestamp64</tp:type>)</dt>
+          <dd>A UNIX timestamp indicating when the message was sent. When
+            <tp:type>Mail_Type</tp:type> is set to <tt>Thread</tt>, this value
+            indicates when the most recent message was sent.
+          </dd>
+
+          <dt>received-timestamp &#8212; x (<tp:type>Unix_Timestamp64</tp:type>)</dt>
+          <dd>A UNIX timestamp indicating when the message was received. When
+            <tp:type>Mail_Type</tp:type> is set to <tt>Thread</tt>, this value
+            indicates when the most recent message was received.
+          </dd>
+
+          <dt>has-attachments &#8212; b</dt>
+          <dd>If true, this mail has attachments.</dd>
+
+          <dt>subject &#8212; s</dt>
+          <dd>
+            The subject of the message. This MUST be encoded in UTF-8.
+          </dd>
+
+          <dt>content-type &#8212; s</dt>
+          <dd>
+            <p>The MIME type of the message content. Two types are currently
+              supported: "text/plain" for plain text, and "text/html" for a
+              HTML document. If omitted, "text/plain" MUST be assumed.
+              Regardless of MIME type, the content MUST be valid UTF-8 (which
+              may require that the Connection transcodes it from a legacy
+              encoding).</p>
+
+            <tp:rationale>
+              <p>All strings on D-Bus must be UTF-8.</p>
+            </tp:rationale>
+          </dd>
+
+          <dt>truncated &#8212; b</dt>
+          <dd>
+            If true, the content is only a partial message; if false or
+            omitted, the content is the entire message.
+          </dd>
+
+          <dt>content &#8212; s</dt>
+          <dd>
+            The body of the message, possibly truncated, encoded as appropriate
+            for "content-type".
+          </dd>
+
+          <dt>folder &#8212; s</dt>
+          <dd>
             The name of the folder containing this e-mails.
-            If unset, inbox will be assumed.
-          </div>
-        </ul>
-        </div>
-      </tp:docstring>
-    </tp:simple-type>
+            If omitted, the inbox SHOULD be assumed.
+          </dd>
+        </dl>
+        </tp:docstring>
+      </tp:member>
+
+      <tp:member name="Value" type="v">
+        <tp:docstring>The value, of whatever type is appropriate for the
+          key.</tp:docstring>
+      </tp:member>
+    </tp:mapping>
 
-    <property name="Capabilities" type="u" access="read"
-      tp:type="Mail_Notification_Flags" tp:name-for-bindings="Capabilities">
+    <property name="MailNotificationFlags" type="u" access="read"
+      tp:type="Mail_Notification_Flags"
+      tp:name-for-bindings="Mail_Notification_Flags">
       <tp:docstring>
         Integer representing the bitwise-OR of supported features for e-mails
-        notification on this server. This property CANNOT change after the 
+        notification on this server. This property MUST NOT change after the
         Connection becomes CONNECTED.
-        <tp:rational>
-          This property explicitly state the behavior and availability
+
+        <tp:rationale>
+          This property indicates the behavior and availability
           of the other properties and signals within this interface. A
-          connection manager that cannot at least set one of the flag
+          connection manager that cannot at least set one of the flags
           in the <tp:type>Mail_Notification_Flags</tp:type>
           SHOULD NOT provide this interface.
-        </tp:rational>
+        </tp:rationale>
       </tp:docstring>
     </property>
 
@@ -321,9 +347,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       tp:name-for-bindings="Unread_Mail_Count">
       <tp:docstring>
         The number of unread messages in the Inbox. Change notification is via
-        <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property
-        can be used if <tt>Supports_Unread_Mail_Count</tt> flag is set in
-        <tp:member-ref>Capabilities</tp:member-ref>.
+        <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property is
+        only useful if <tt>Supports_Unread_Mail_Count</tt> is set in the
+        <tp:member-ref>MailNotificationFlags</tp:member-ref>; otherwise, it MUST be
+        zero.
       </tp:docstring>
     </property>
 
@@ -331,9 +358,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       tp:name-for-bindings="Unread_Mails" access="read">
       <tp:docstring>
         A array of unread <tp:type>Mail</tp:type>s. Change notification is via
-        <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property
-        can be used if <tt>Supports_Unread_Mails</tt> flag is set in
-        <tp:member-ref>Capabilities</tp:member-ref>.
+        <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property is
+        only useful if <tt>Supports_Unread_Mails</tt> is set in
+        <tp:member-ref>MailNotificationFlags</tp:member-ref>; otherwise, it MUST be
+        an empty list.
       </tp:docstring>
     </property>
 
@@ -341,23 +369,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <arg name="Mails" type="aa{sv}" tp:type="Mail[]">
         <tp:docstring>
           An array of <tp:type>Mail</tp:type>s. Those e-mail MAY NOT have the
-          "id" key or MAY have an "id" key that is not unique.
+          "id" key.
           <tp:rationale>
-            In this context, the "id" key does not make much sense since
-            e-mails will only be sent once. CMs may still set it to put
-            additional information for method 
-            <tp:member-ref>RequestMailURL</tp:member-ref>.
+            In this context, the "id" key is not very important since
+            e-mails will only be sent once. CMs may still set it to identify
+            the e-mail when <tp:member-ref>RequestMailURL</tp:member-ref>
+            is called.
           </tp:rationale>
         </tp:docstring>
       </arg>
 
       <tp:docstring>
         Emitted when new e-mails messages arrive to the inbox associated with
-        this connection. This signal is used for protocol that are NOT able
-        to maintained <tp:member-ref>UnreadMails</tp:member-ref> list but
-        receives real-time notification about newly arrived e-mails. It MAY be
-        emited only if <tt>Emits_Mails_Received</tt> flag is set in
-        <tp:member-ref>Capabilities</tp:member-ref>.
+        this connection. This signal is used for protocols that are not able
+        to maintain the <tp:member-ref>UnreadMails</tp:member-ref> list, but
+        do provide real-time notification about newly arrived e-mails. It MUST
+        NOT be emitted unless <tt>Emits_Mails_Received</tt> is set in
+        <tp:member-ref>MailNotificationFlags</tp:member-ref>.
       </tp:docstring>
     </signal>
 
@@ -370,33 +398,37 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:docstring>
       </arg>
       <arg name="Mails_Added" type="aa{sv}" tp:type="Mail[]">
-        <tp:docstring>
-          A list of <tp:type>Mail</tp:type> that are being added or updated in
-          <tp:member-ref>UnreadMails</tp:member-ref>. This list will be
-          empty if the protocol does NOT support listing unread e-mails
-          or threads.
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A list of <tp:type>Mail</tp:type> that are being added or updated
+            in <tp:member-ref>UnreadMails</tp:member-ref>.</p>
+
           <tp:rationale>
-            Mails MAY be updated when the URL information (url and POST Data)
-            have changed, or senders were added or removed from an e-mails
-            thread (see <tp:type>Mail_Type</tp:type>).
+            <p>Mails may be updated when the URL information (URL and POST data)
+              have changed, or senders were added or removed from an e-mail
+              thread (see <tp:type>Mail_Type</tp:type>_Thread).</p>
           </tp:rationale>
+
+          <p>If the <tt>Supports_Unread_Mails</tt> flag is not set, this list
+            MUST be empty, even if Count has increased.</p>
         </tp:docstring>
       </arg>
       <arg name="Mails_Removed" type="as">
         <tp:docstring>
-          A list of e-mails ID that are being removed from
-          <tp:member-ref>UnreadMails</tp:member-ref>. This list will be
-          empty if the protocol does NOT support listing unread e-mails
-          or threads.
+          A list of e-mail IDs that are being removed from
+          <tp:member-ref>UnreadMails</tp:member-ref>.
+          If the <tt>Supports_Unread_Mails</tt> flag is not set, this list
+          MUST be empty, even if Count has decreased.
         </tp:docstring>
       </arg>
-      <tp:docstring>
-        Emitted when <tp:member-ref>UnreadMails</tp:member-ref> or
-        <tp:member-ref>UnreadMailCount</tp:member-ref> have changed. It MAY be
-        emited only if <tt>Supports_Unread_Mail_Count</tt> flag is set in
-        <tp:member-ref>Capabilities</tp:member-ref>. <tt>mails_added</tt> and
-        <tt>mails_removed</tt> MAY NOT be empty list if 
-        <tt>Supports_Unread_Mails</tt> flag is set.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted when <tp:member-ref>UnreadMails</tp:member-ref> or
+          <tp:member-ref>UnreadMailCount</tp:member-ref> have changed. It MUST
+          NOT be emited if <tt>Supports_Unread_Mail_Count</tt> flag is not set
+          in <tp:member-ref>MailNotificationFlags</tp:member-ref>.</p>
+
+        <p><tt>Mails_Added</tt> and
+          <tt>Mails_Removed</tt> MUST be empty if the
+          <tt>Supports_Unread_Mails</tt> flag is not set.</p>
       </tp:docstring>
     </signal>
 
@@ -406,39 +438,34 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <p>This method subscribes a client to the notification interface. This
           MUST be called by clients before using this interface.</p>
 
-        <p>The CM tracks a subscription count (like a refcount) for each
-          unique bus name that has called Subscribe(). When a client calls
+        <p>The Connection tracks a subscription count (like a refcount) for
+          each unique bus name that has called Subscribe(). When a client calls
           Unsubscribe(), it releases one "reference". If a client exits
-          (or crash), it releases all of its "references".</p>
+          (or crashes), the Connection releases all "references" held on its
+          behalf.</p>
 
         <tp:rationale>
-            The reference count imposed on the subscription SHOULD simplify
+          <p>The reference count imposed on the subscription simplifies
             implementation of client running in the same process
-            (e.g. plug-ins). Two plug-ins interested in mail notification can
-            call Subscribe independently without relying on the CM to handle
-            this particular action.
-        </tp:rationale>
-
-        <tp:rationale>
-            This method exists to initiate real time messages in the case
-            at least one client is subscribed. This may also be used to reduce
-            memory and network overhead when there is no active subscription.
-            An example of protocol that benifits from this method is the
-            Google XMPP Mail Notification extension. In this protocol, the CM
-            receives a notification telling that something has changed. To get
-            more information, the CM must request this information. Knowing
-            that nobody is currently interested in this information, the CM
-            can avoid generating useless network traffic. In the same situation,
-            the CM may free the list of unread messages and reduce memory
-            overhead.
+            (e.g. plug-ins): two plug-ins interested in mail notification can
+            call Subscribe and Unsubscribe independently without interfering
+            with each other.</p>
+
+          <p>This method exists to reduce memory and network overhead when
+            there is no active subscription. An example of a protocol that
+            benefits from this method is the Google XMPP Mail Notification
+            extension: in this protocol, the CM receives a notification
+            that something has changed, but to get more information, the CM
+            must request this information. Knowing that nobody is currently
+            interested in this information, the CM can avoid generating
+            useless network traffic. Similarly, the CM may free
+            the list of unread messages to reduce memory overhead.</p>
         </tp:rationale>
 
       </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.NotAvailable"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
       </tp:possible-errors>
     </method>
 
@@ -446,20 +473,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         tp:name-for-bindings="Unsubscribe">
       <tp:docstring>
         This method unsubscribes a client from the notification interface.
-        This SHOULD be called when a client no longer need the mail
-        notification interface.
+        This SHOULD be called by each client that has successfully called
+        Subscribe when it no longer needs the mail notification interface.
+
         <tp:rationale>
-          When the last client unsubscribe from this interface, the CM may
-          free any uneeded data and reduce network traffic. See
-          <tp:member-ref>Unsubscribe</tp:member-ref> for more rationale on
-          this topic.
+          See <tp:member-ref>Subscribe</tp:member-ref> for rationale.
         </tp:rationale>
       </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.NotAvailable"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            Raised if the client calling this method has no references to
+            release.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
       </tp:possible-errors>
     </method>
 
@@ -467,21 +495,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       tp:name-for-bindings="Request_Inbox_URL">
       <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" >
         <tp:docstring>
-          A struture that contains URL and any additional data to open Web
-          mail client without re-authentication.
+          A struture containing a URL and optional additional data to open a
+          webmail client, without re-authentication if possible.
         </tp:docstring>
       </arg>
       <tp:docstring>
-        This method creates and returns an URL and an optionnal POST data that
-        allow openning the Inbox folder of your Web mail account. This URL may
-        contains token with short lifetime. Thus, a client SHOULD NOT reuse it
-        and request a new URL whenever it is needed. This method is implemented
-        only if <tt>Supports_Request_Inbox_URL</tt> flag is set in
-        <tp:member-ref>Capabilities</tp:member-ref>.
+        This method creates and returns a URL and an optional POST data that
+        allow opening the Inbox folder of a webmail account. This URL MAY
+        contain tokens with a short lifetime, so clients SHOULD request a new
+        URL for each visit to the webmail interface. This method is implemented
+        only if the <tt>Supports_Request_Inbox_URL</tt> flag is set in
+        <tp:member-ref>MailNotificationFlags</tp:member-ref>.
+
         <tp:rationale>
-          We are NOT using properties here because the tokens MAY NOT be shared
-          between clients and that network may be required to obtain the
-          information that leads to authentication free Web access.
+          We are not using properties here because the tokens are unsuitable
+          for sharing between clients, and network round-trips may be required
+          to obtain the information that leads to authentication free webmail
+          access.
         </tp:rationale>
       </tp:docstring>
       <tp:possible-errors>
@@ -495,54 +525,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       tp:name-for-bindings="Request_Mail_URL">
       <arg direction="in" name="ID" type="s">
         <tp:docstring>
-          The mail ID as found in <tp:type>Mail</tp:type> structure. If this
-          key is missing, use the empty string.
+          The mail's <tt>id</tt> as found in the <tp:type>Mail</tp:type>
+          structure, or the empty string if no <tt>id</tt> key was provided.
         </tp:docstring>
       </arg>
       <arg direction="in" name="URL_Data" type="s">
         <tp:docstring>
-          An opaque string that contains information required by CM to build
-          a correct URL for opening Web mail client without re-authentication.
-          This token is part of <tp:type>Mail</tp:type> structure, if it's
-          missing, use the empty string.
+          The <tt>url-data</tt> as found in the <tp:type>Mail</tp:type>
+          structure, or the empty string if no <tt>url-data</tt> key was
+          provided.
         </tp:docstring>
       </arg>
       <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" >
         <tp:docstring>
-          A struture that contains URL and any additional data to open Web
-          mail client without re-authentication.
+          A struture that contains a URL and optional additional data to open a
+          webmail client, without re-authentication if possible.
         </tp:docstring>
       </arg>
       <tp:docstring>
-        This method creates and return a URL and optionnal POST data that
-        allow openning specific mail of your Web mail account. Refer to
-        <tp:member-ref>RequestInboxURL</tp:member-ref> for rationale. This
+        This method creates and returns a URL and optional POST data that
+        allow opening a specific mail in a webmail interface. This
         method is implemented only if <tt>Supports_Request_Mail_URL</tt> flag
-        is set in <tp:member-ref>Capabilities</tp:member-ref>.
-      </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.NotImplemented"/>
-      </tp:possible-errors>
-    </method>
-
-    <method name="RequestComposeURL"
-      tp:name-for-bindings="Request_Compose_URL">
-      <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" >
-        <tp:docstring>
-          A struture that contains URL and any additional data to open Web
-          mail client without re-authentication.
-        </tp:docstring>
-      </arg>
-      <tp:docstring>
-        This method assembles and returns an URL and optional POST data that
-        allow openning the mail compositer page of your Web mail account.
-        This method is implemented only if <tt>Supports_Request_Compose_URL</tt>
-        flag is set in <tp:member-ref>Capabilities</tp:member-ref>.
+        is set in <tp:member-ref>MailNotificationFlags</tp:member-ref>.
         <tp:rationale>
-          The goal is to allow a Web mail user to have the same level of
-          integration as if he were using a native mail client.
+          See <tp:member-ref>RequestInboxURL</tp:member-ref> for design
+          rationale.
         </tp:rationale>
       </tp:docstring>
       <tp:possible-errors>
@@ -554,96 +561,73 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>An interface to support receiving notifications about a e-mail
-        account associated with this connection. It is intended that the
-        connection manager has the means to provide necessary information
-        so that the client is always able to open a web based mail client
-        without having to re-authenticate.
-      </p>
-      <p>
-        To use this interface, a client MUST first subscribe using the
+        account associated with this connection.</p>
+
+      <p>In protocols where this is possible, this interface also allows the
+        connection manager to provide the necessary information for clients
+        to open a web-based mail client without having to re-authenticate.</p>
+
+      <p>To use this interface, a client MUST first subscribe using the
         <tp:member-ref>Subscribe</tp:member-ref> method. The subscription
         mechanic aims at reducing network traffic and memory footprint in the
         situation where nobody is currently interesting in provided
-        information.
-      </p>
-      <p>
-        Protocol often have different level of Mail Notification support. To
-        make it more explicit, the interface provides a property called
-        <tp:member-ref>Capabilities</tp:member-ref>. Possible value are
-        described by <tp:type>Mail_Notification_Flags</tp:type>. Not all
-        combinations are valid. We can regroup the mail notification in four
-        different combinations.
-      </p>
-      <p>
-        <b>1) Supports_Unread_Mail_Count only:</b>
-        <br/>
-        This flag is generally combined with other flags, but provides
-        sufficient information to be usefull. The mail count is supported
-        by most protocols including MSN, Yahoo and Google Talk. It allows 
-        a UI to permanantly display messages like 'GMail: 4 unread messages'.
-      </p>
-      <p>
-        <b>2) Emist_Mails_Received only:</b>
-        <br/>
-        In this case, the CM does not keep track of any mails. It simply emits
-        information whenever they arrived to it. Those events may be used for
-        short term display (like notification popup) to inform the user. No
-        protocol is known to only supported this single feature, but it is
-        useful for certain library integration that does not implement
-        tracking of count or have a buggy counter implementation.
-        <tp:rationale>
-          It's always better to remove a feature then enabling one that does
-          not behave properly.
-        </tp:rationale>
-      </p>
-      <p>
-        <b>3) Supports_Unread_Mail_Count and Supports_Unread_Mails:</b>
-        <br/>
-        This allow full state recovery of unread mail status. It is provided
-        by Google XMPP Mail Notification Extension. With this set of flag,
-        a client could have same display has case 1, and have let's say a
-        plus button to show more detailed information. Refer to
-        <tp:type>Mail</tp:type> documentation for the list of details that
-        MAY be provided.
-      </p>
-      <p>
-        <b>4) Supports_Unread_Mail_Count and Emits_Mails_Received</b>
-        <br/>
-        This is the most common level of support, it is provided by protocols
-        like MSN and Yahoo. This would result in a combination of case 1 and 2
-        where the client could display a counter and real-time notification.
-      </p>
-      <p>
-        In case 1, 3 and 4, client SHOULD connect to signal
-        <tp:member-ref>UnreadMailsChanged</tp:member-ref> to get updated with
-        latest value of <tp:member-ref>UnreadMailCount</tp:member-ref>. In
-        case 3, this signal also provides updates of
-        <tp:member-ref>UnreadMails</tp:member-ref> property.
-      </p>
-      <p>
-        In case 2 and 4, client MAY connect to signal
-        <tp:member-ref>MailsReceived</tp:member-ref> to get real-time
-        notification about newly arrived e-mails.
-      </p>
-      <p>
-        Other independant features promoted within the
-        <tp:member-ref>Capabilities</tp:member-ref> are the RequestSomethingURL
-        methods. Those requests are used to obtain authentication free URL that
-        will allow client to open web base mail client. Those capabilities
-        are all optional, but flag <tt>Supports_Request_Inbox_URL</tt> is
-        recommanded for case 1, 3 and 4. Flag 
-        <tt>Supports_Request_Mail_URL</tt> is mostly usefull for case 1, 3
-        and 4, but client SHOULD fallback to Inbox URL if missing. Finally,
-        flag <tt>Supports_Request_Compose_URL</tt> is a special feature that
-        allow accessing the mail creation web interface with a single click.
-        This feature is simply optional.
-      </p>
+        information. When done with this interface, clients SHOULD call
+        <tp:member-ref>Unsubscribe</tp:member-ref> to release resources in
+        the CM.</p>
+
+      <p>Protocols have various different levels of Mail Notification support.
+        To describe the level of support, the interface provides a property
+        called <tp:member-ref>MailNotificationFlags</tp:member-ref>.
+        Not all combinations are valid; protocols can be divided into four
+        categories as follows.</p>
+
+      <p>Connections to the most capable protocols, such as Google's XMPP Mail
+        Notification extension, have the Supports_Unread_Mails flag (this
+        implies that they must also have Supports_Unread_Mail_Count, but not
+        Emits_Mails_Received). On these connections, clients
+        requiring change notification MUST monitor the
+        <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal, and
+        either recover the initial state from the
+        <tp:member-ref>UnreadMails</tp:member-ref> property (if they require
+        details other than the number of mails) or the
+        <tp:member-ref>UnreadMailCount</tp:member-ref> property (if they
+        are only interested in the number of unread mails). The
+        <tp:member-ref>MailsReceived</tp:member-ref> signal is never emitted
+        on these connections, so clients that will display a short-term
+        notification for each new mail MUST do so in response to emission of
+        the <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal.</p>
+
+      <p>The most common situation, seen in protocols like MSN and Yahoo, is
+        that the number of unread mails is provided and kept up-to-date,
+        and a separate notification is emitted with some details of each new
+        mail. This is a combination of the following two features, and clients
+        SHOULD implement one or both as appropriate for their requirements.</p>
+
+      <p>On protocols that have the Emits_Mails_Received flag (which implies
+        that they do not have Supports_Unread_Mails), the CM does not keep
+        track of any mails; it simply emits a notification whenever new mail
+        arrives. Those events may be used for short term display (like a
+        notification popup) to inform the user. No protocol is known to support
+        only this feature, but it is useful for integration with libraries that
+        that do not implement tracking of the number of mails. Clients
+        requiring these notifications MUST monitor the
+        <tp:member-ref>MailsReceived</tp:member-ref> signal on any connections
+        with this flag.</p>
+
+      <p>On protocols that have the Supports_Unread_Mail_Count flag but not
+        the Supports_Unread_Mails flag, clients cannot display complete
+        details of unread email, but can display an up-to-date count of the
+        <em>number</em> of unread mails. To do this, they must monitor the
+        <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal, and
+        retrieve the initial state from the
+        <tp:member-ref>UnreadMailCount</tp:member-ref> property.</p>
+
       <p>
-        When done with this interface, client SHOULD call
-        <tp:member-ref>Unsubscribe</tp:member-ref>. If no more clients are
-        subscribed, the CM will then be able to free any uneeded memory and
-        reduce network traffic.
-      </p>
+        Orthogonal features described by the
+        <tp:member-ref>MailNotificationFlags</tp:member-ref> property include the
+        RequestSomethingURL methods, which are used to obtain URLs allowing
+        clients to open a webmail client. Connections SHOULD support as many
+        of these methods as possible.</p>
     </tp:docstring>
   </interface>
 </node>
diff --git a/src/conn-mail-notif.c b/src/conn-mail-notif.c
index 3316f2b49..d277ba25a 100644
--- a/src/conn-mail-notif.c
+++ b/src/conn-mail-notif.c
@@ -48,7 +48,7 @@
 
 enum
 {
-  PROP_CAPABILITIES,
+  PROP_MAIL_NOTIFICATION_FLAGS,
   PROP_UNREAD_MAIL_COUNT,
   PROP_UNREAD_MAILS,
   NUM_OF_PROP,
@@ -693,21 +693,21 @@ conn_mail_notif_properties_getter (GObject *object,
 
   if (G_UNLIKELY (prop_quarks[0] == 0))
     {
-      prop_quarks[PROP_CAPABILITIES] = g_quark_from_static_string ("Capabilities");
+      prop_quarks[PROP_MAIL_NOTIFICATION_FLAGS] = g_quark_from_static_string ("MailNotificationFlags");
       prop_quarks[PROP_UNREAD_MAIL_COUNT] = g_quark_from_static_string ("UnreadMailCount");
       prop_quarks[PROP_UNREAD_MAILS] = g_quark_from_static_string ("UnreadMails");
     }
 
   DEBUG ("MailNotification get property %s", g_quark_to_string (name));
 
-  if (name == prop_quarks[PROP_CAPABILITIES])
+  if (name == prop_quarks[PROP_MAIL_NOTIFICATION_FLAGS])
     {
       if (conn->features & GABBLE_CONNECTION_FEATURES_GOOGLE_MAIL_NOTIFY)
         g_value_set_uint (value,
-            GABBLE_MAIL_NOTIFICATION_SUPPORTS_UNREAD_MAIL_COUNT
-            | GABBLE_MAIL_NOTIFICATION_SUPPORTS_UNREAD_MAILS
-            | GABBLE_MAIL_NOTIFICATION_SUPPORTS_REQUEST_INBOX_URL
-            | GABBLE_MAIL_NOTIFICATION_SUPPORTS_REQUEST_MAIL_URL
+            GABBLE_MAIL_NOTIFICATION_FLAG_SUPPORTS_UNREAD_MAIL_COUNT
+            | GABBLE_MAIL_NOTIFICATION_FLAG_SUPPORTS_UNREAD_MAILS
+            | GABBLE_MAIL_NOTIFICATION_FLAG_SUPPORTS_REQUEST_INBOX_URL
+            | GABBLE_MAIL_NOTIFICATION_FLAG_SUPPORTS_REQUEST_MAIL_URL
             );
       else
         g_value_set_uint (value, 0);
diff --git a/src/connection.c b/src/connection.c
index e4be148bf..e3fd2b430 100644
--- a/src/connection.c
+++ b/src/connection.c
@@ -729,7 +729,7 @@ gabble_connection_class_init (GabbleConnectionClass *gabble_connection_class)
         { NULL }
   };
   static TpDBusPropertiesMixinPropImpl mail_notif_props[] = {
-        { "Capabilities", NULL, NULL },
+        { "MailNotificationFlags", NULL, NULL },
         { "UnreadMailCount", NULL, NULL },
         { "UnreadMails", NULL, NULL },
         { NULL }