[Telepathy] Comments on telepathy-spec-contact-info branch

[Simon McVittie]

Comments welcomed from client authors (Zdra?) and anyone with
involvement in Evolution/KAddresbook/etc., since they'll be the ones
using this...

(See <http://projects.collabora.co.uk/~monkey/telepathy-spec-contact-info/>)

+  <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>

I don't think these are correct.

+        <tp:docstring>
+          An array of structs containing:
+          <ul>
+            <li>a string information field</li>

"A string field name"?

+    <method name="GetContactInfo">
+      <arg direction="in" name="contact" type="u">
+        <tp:docstring>
+          An integer handle of the contact to request his informations for

"An integer handle of the contact whose information is to be requested"?

+      <p>An interface for requesting information for contacts on a given connection and publishing
+    your own information.</p>
+
+      <p>The following types and field names should be used where appropriate: </p>

Where did you get these particular fields from? It seems sensible
to get them from some sort of reference rather than inventing Yet
Another set of conventions. I'd go for (a simplified form of) vCard,
probably; RFC2426. hCard <http://microformats.org/wiki/hcard> might also
be worth a look.

As a general comment: we're not supporting multiples here. Multiple
names would obviously be silly, but multiple mobile phone numbers are
entirely reasonable to have. Perhaps we should throw some arrays in
somewhere...

+      <dl>
+        <dt>s:full-name</dt><dd>Full name</dd>

Same as vCard's FN, for what it's worth

+        <dt>s:family-name</dt><dd>Family name</dd>
+        <dt>s:first-name</dt><dd>First name</dd>

First/last and given/family are distinct; in principle, a particular protocol
might have both, one or neither. vCard uses family and given names; I think if
we just pick one or the other, we should follow its lead.

(Consider Chinese and Japanese names where the family name is written
first, to see the distinction.)

vCard also has additional (middle) names, honorific prefixes and
honorific suffixes. I think we can probably skip those...

+        <dt>s:url</dt><dd>URL of a personal webpage</dd>

URL in vCard

+        <dt>s:birthday</dt><dd>Date of birthday. Format used is YYYY-MM-DD</dd>

vCard uses BDAY, but I think expanding the name is reasonable.

+        <dt>s:email-home</dt><dd>Personal email</dd>

vCard equivalent is EMAIL; vCard makes no distinction between personal
and work e-mail, but I think this is a useful distinction to make.

+        <dt>s:tel-home</dt><dd>Home phone</dd>

vCard equivalent is TEL;TYPE=home,voice.

+        <dt>s:fax-home</dt><dd>Home fax</dd>

vCard equivalent is TEL;TYPE=home,fax.

+        <dt>s:street-home</dt><dd>Home address: street</dd>
+        <dt>s:locality-home</dt><dd>Home address: locality</dd>
+        <dt>s:region-home</dt><dd>Home address: region</dd>
+        <dt>s:postal-home</dt><dd>Home address: postal code</dd>
+        <dt>s:country-home</dt><dd>Home address: country</dd>

vCard equivalent is ADR;TYPE=home, which is divided into post office
box, extended address (e.g. flat number), street address, locality, region,
postal code and country. Perhaps we should allow the smaller
subdivisions too, just to be consistent.

+        <dt>s:email-work</dt><dd>Business email</dd>
+        <dt>s:tel-work</dt><dd>Business phone</dd>
+        <dt>s:fax-work</dt><dd>Businnes fax</dd>

EMAIL, TEL;TYPE=work,voice and TEL;TYPE=work,fax.

+        <dt>s:company-work</dt><dd>Company</dd>
+        <dt>s:department-work</dt><dd>Department</dd>

-work is redundant, and "company" is misleading e.g. if someone works
for a charity or university. vCard has ORG (expanding that to
organization would be reasonable).

vCard's ORG is split into "the organization name, followed by one or
more levels of organizational unit names". I think we can simplify that
to org-name and org-department (or something) with minimal loss of
information.

+        <dt>s:title-work</dt><dd>Position</dd>

vCard TITLE. -work is a bit redundant, but does help to indicate what
this field means.

<dt>s:title</dt><dd>Job title or functional position</dd> mirrors the
language in the vCard RFC. The example the RFC gives is "Director,
Research and Development".

+        <dt>s:role-work</dt><dd>Role</dd>

vCard ROLE, "to specify information concerning the role, occupation or
business category of the object the vCard represents". The example the
RFC gives is "Programmer".

+        <dt>s:street-work</dt><dd>Work address: street</dd>
+        <dt>s:locality-work</dt><dd>Work address: locality</dd>
+        <dt>s:region-work</dt><dd>Work address: region</dd>
+        <dt>s:postal-work</dt><dd>Work address: postal code</dd>
+        <dt>s:country-work</dt><dd>Work address: country</dd>

vCard ADR;TYPE=work. See home for comments.

+        <dt>s:tel-mobile</dt><dd>Mobile phone</dd>

vCard TEL;TYPE=cell. Perhaps tel-cell to be consistent with vCard?
tel-mobile is a more obvious phrasing, though.

+        <dt>s:description</dt><dd>Description</dd>