[uf-discuss] Some hcard feedback from a vCard implementor

[Sam Roberts]

On Tue, Apr 04, 2006 at 11:38:36AM -0700, Ryan King wrote:
> On Apr 4, 2006, at 10:25 AM, Sam Roberts wrote:
> 
> >Hi, I'm the author of Vpim (http://vpim.rubyforge.org), an
> >implementation (in progress) of vCard and iCalendar encoding/decoding
> >for ruby. Some comments on the hcard specification.
> >
> >I notice hcard is trying to deduce semantic information from FN,  
> >but I'd
> >like to convince you this is a Bad Idea.
> 
> Don't bother, we already now its a bad idea. The "Implied N  
> optimization" only applies in certain cases. In other cases, you can  
> specify the N fields. See http://microformats.org/wiki/hcard#Implied_. 
> 22n.22_Optimization.

You have a description on the wiki of deriving N from FN, which assumes
things about the format of FN that are culturally specific (first names
before last, for example), when the very absence of N is a violation of
the vCard spec.

It sure looked to me like the spec is describing how to do that which
shouldn't be done. Maybe saying "we know its a bad idea" would be a good
idea. I don't see why you have any rules at all.  Have you actually
found non-conformant vCards in the wild that lack a N?

> >...
> >Couple other thoughts:
> >
> >- You don't mention internationalization. Its a weakness in vCard. I'd
> >  suggest that you specify hcard as being in unicode, with utf-8  
> >without
> >  a BOM as the preferred encoding.
> 
> There's no need to specify an encoding for hcard, that problem is  
> deferred to the (x)html layer. Per the parsing document (http:// 
> microformats.org/wiki/hcard-parsing), those encodings should be honored.
> 
> >  A note on what I've noticed about AddressBook. It sounds like you
> >  already noticed that Apple mangles utf-8 on import (I haven't tried
> >  utf-8 with a BOM, though). If interop with Apple is something you're
> >  looking for, then you need to be either ASCII (or maybe some ancient
> >  Mac character set), or else UCS-2. They started adding a BOM to the

UCS-2/UTF-16

> >  start of their exported UCS-2 in the last year or so. Putting one in
> >  is probably a good idea. I wouldn't try to embed character sets  
> >inside
> >  the card using parameters, not likely to be very portable.
> 
> Actually, we already have compatibility with Apple's Addressbook.app,  
> by using UTF-16.

Good, I am happy to hear you are doing that.

I was concerned you were using the ;CHARSET= workaround described on the
wiki:

 Apple Address Book

 On both OSX.3 and OSX.4.
 general comments

     * There are issues with importing UTF-8 vCards. Apple Address Book
	 * appears to treat .vcf files in the file system NOT as UTF-8, but
	 * rather perhaps Mac Roman?
	     o Workaround: Explicitly specify the UTF-8 charset for
		vCard properties/fields that have non-ASCII-7 characters. 

> I believe newer versions of AddressBook have fixed  this bug.

What bug? I didn't describe any bugs. Mangling utf-8 isn't a bug, how
was AddressBook supposed to know utf-8 is my favorite character set?

> >- The spec reads like a bunch of simple examples, not a spec,  
> >though the
> >  discussion of design principles is nice. hcalendar is even more
> >  lacking, its just a cut-n-paste of hcard, with lots of information
> >  removed! You won't get good interop without a more detailed spec
> >  and great examples.
> 
> Hmm, I could consider the simplicity a feature. If there are areas of  
> the spec that need more detail, please point them out, but I'm not a  

I'm trying, my friend, I'm trying!

> Are you looking to convert vCards into generic XML or into hCards?

hcards, if I was doing generic XML, I'd be looking over here:

  http://www.oasis-open.org/cover/vcard.html

and probably using:

  http://www.jabber.org/jeps/jep-0054.html

You guys do know about the other XML versions of vCard, right?

> >  vCard --
> >
> >    name[;pname=[pvalue[,pvalue]*]]*:value
> >
> >   ==>
> >
> >   hcard --
> >
> >	<blah class="NAME">
> >	  <span type="pname">pvalue</span>
> >	  value
> >	</blah>
> >
> >   Followed by the short list of special rules/"optimizations".
> 
> I'm not sure what you're asking for here.

Take this example from the wiki:

	<span class="tel">
	<span class="type">home</span>:
	<span class="value">+1.415.555.1212</span>
	</span>

Now remove the example from the spec. How would a reader be able to know
from the "specification" that "span" elements are to be used in the XML?
Maybe I missed it, but I don't see a specification, I see a design
rationale (which is much appreciated, and sorely missing from many
specs), and I see lots of examples.

> >- Don't make their mistake. Please put at least two examples in your
> >  spec: an organization, and an individual. And make them COMPLICATED.
> >  Two photos, a bunch of different kinds of addresses, real names
> >  (middle names, suffixes, etc.).
> 
> I like have the spec simple, we have other space for examples: http:// 
> microformats.org/wiki/hcard-examples.

I did indeed miss that page. It actually makes me more concerned, not
less.

I'm a huge fan of examples, but they don't replace a spec.

The goal of "simplicity" is met by the spec if it can be used to
implement. This spec can't be used without the examples, as far as I can
tell. Its text isn't normative. Theres no way I can see to go through
those examples and say for each one "this field is transcoded from vCard
to hCard like this because it said to do ... in the spec".

Its the opposite, you have to read the examples, and back-derive the
specification from them because the rules aren't in the spec, as far as
I can tell.

Specs that rely over-heavily on the examples (the iCalendar RFC in
particular is bad for this) have the characteristic that when you try to
do something that you don't have an example for, you guess at how to
handle it, and peoples guesses tend not to be the same.

Specific example, the NOTE field. Its value type is TEXT. TEXT can have
newlines, they are encoded as the two characters '\', and 'n'.  The
hcard spec doesn't say how to handle TEXT, doesn't even mention its
existence, AFAICT, and I can't find an example where \n was used on
/hcard-examples, so I'm not sure how newlines would get represented in
hcard.

Anyhow, its my suggestion that the spec would be more useful if it was
written so the text is normative and the examples serve only as
illustration, and to help implementors write tests.

Cheers,
Sam