[Telepathy-commits] [telepathy-spec/master] ContactInfo: prefix type parameters with the type-parameter name

[Simon McVittie]

This means we can have language=foo as well as type=bar.

Also, add NICKNAME to the example vCard, to illustrate how we split
multi-valued vCard fields into multiple fields.
---
 spec/Connection_Interface_Contact_Info.xml |   67 +++++++++++++++++++---------
 1 files changed, 45 insertions(+), 22 deletions(-)

diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml
index e7b033b..bba5e89 100644
--- a/spec/Connection_Interface_Contact_Info.xml
+++ b/spec/Connection_Interface_Contact_Info.xml
@@ -31,28 +31,48 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:docstring>
       </tp:member>
       <tp:member type="as" name="Parameters">
-        <tp:docstring>
-          A list of (lowercased) vCard type parameters applicable to this field.
-          For example, a contact's preferred home address would have parameters
-          'home' and 'pref'.
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A list of vCard type parameters applicable to this field, with their
+            values. The type parameter names, and any values that are
+            case-insensitive in vCard, MUST be in lower case. For example, a
+            contact's preferred home address would have parameters
+            'type=home' and 'type=pref'.</p>
+
+          <tp:rationale>
+            The type parameter 'type' is likely to be the most common, but
+            there can be others, such as 'language=en'.
+          </tp:rationale>
+
+          <p>Characters which are required to be escaped in vCard type
+            parameters should not be escaped in this list. For instance,
+            a field "X-FOO;SEMICOLON=\;:bar" in a vCard would become
+            ('x-foo', ['semicolon=;'], ['bar']) in this interface.</p>
 
           <tp:rationale>
-            This is a list of strings rather than a bitwise OR of enum members
-            because vCard type parameters are essentially arbitrary strings.
+            This avoids Telepathy UIs having to understand the escaping and
+            unescaping rules for vCards. The type parameter name is not
+            allowed (by RFC 2425) to contain an '=' character, so no ambiguity
+            is introduced.
           </tp:rationale>
         </tp:docstring>
       </tp:member>
       <tp:member type="as" name="Field_Value">
-        <tp:docstring>
-          For unstructured vCard fields (such as 'fn', a formatted name
-          field), a single-element array containing the field's value; for
-          structured fields (such as 'adr', an address field), an array
-          corresponding to the semicolon-separated elements of the field (with
-          empty strings for empty elements).  A vCard field with multiple
-          comma-separated values should be represented by several
-          <tp:type>Contact_Info_Field</tp:type>s.  Characters which are
-          required to be escaped in vCard values, such as semi-colons, should
-          not be escaped in this list.
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>For unstructured vCard fields (such as 'fn', a formatted name
+            field), a single-element array containing the field's value.</p>
+
+          <p>For structured fields (such as 'adr', an address field), an array
+            corresponding to the semicolon-separated elements of the field (with
+            empty strings for empty elements).</p>
+
+          <p>A vCard field with multiple comma-separated values, such as
+            'nickname', should be represented by several
+            <tp:type>Contact_Info_Field</tp:type>s.</p>
+
+          <p>Characters which are required to be escaped in vCard values, such as
+            semi-colons and newlines, should not be escaped in this list (e.g. if
+            a value contains a newline, the data passed over D-Bus should
+            contain a literal newline character).</p>
 
           <tp:rationale>
             An earlier draft of this interface split structured vCard fields
@@ -111,6 +131,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    EMAIL;TYPE=INTERNET,PREF:wee.ninja at collabora.co.uk
    EMAIL;TYPE=INTERNET:wee.ninja at example.com
    URL:http://www.thinkgeek.com/geektoys/plush/8823/
+   NICKNAME:HR Ninja,Enforcement Ninja
    END:vCard</pre>
 
         <p>would be represented by (in Python-like syntax):</p>
@@ -120,13 +141,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   ('fn', [], ['Wee Ninja']),
   ('n', [], ['Ninja', 'Wee', '', '', '-san']),
   ('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']),
-  ('adr', ['work','postal','parcel'], ['','','11 Kings Parade','Cambridge',
-                                       'Cambridgeshire','CB2 1SJ','UK']),
-  ('tel', ['voice','work'], ['+44 1223 362967']),
-  ('tel', ['voice','work'], ['+44 7700 900753']),
-  ('email', ['internet','pref'], ['wee.ninja at collabora.co.uk']),
-  ('email', ['internet'], ['wee.ninja at example.com']),
+  ('adr', ['type=work','type=postal','type=parcel'],
+   ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']),
+  ('tel', ['type=voice','type=work'], ['+44 1223 362967']),
+  ('tel', ['type=voice','type=work'], ['+44 7700 900753']),
+  ('email', ['type=internet','type=pref'], ['wee.ninja at collabora.co.uk']),
+  ('email', ['type=internet'], ['wee.ninja at example.com']),
   ('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']),
+  ('nickname', [], ['HR Ninja']),
+  ('nickname', [], ['Enforcement Ninja'])
 ]</pre>
       </tp:docstring>
     </tp:struct>
-- 
1.5.6.5