Microformats Wiki - User contributions [en]

datetime-design-pattern

2008-07-30T20:47:49Z

Atamido: /* Machine-data in class */

<h1> Datetime Design Pattern </h1>
This is a page for exploring a datetime design pattern.

{{TOC-right}}

== Purpose ==
* Use the [[datetime-design-pattern]] to make datetimes that are human readable also formally machine readable.

== Practical Need ==
* This design pattern arose as a result of solving the practical need for human readable dates for [[hcalendar|hCalendar]].

== How to use it ==
* enclose the human-friendly datetime that you want to make machine readable with <code><abbr></code>
* as per the [[class-design-pattern]], add the appropriate <code>class</code> attribute to the <code>abbr</code> element
* add a <code>title</code> attribute to the <code>abbr</code> element with the machine readable [[iso-8601|ISO8601]] datetime or date as the value

==Current uses==

The pattern, which is now available as part of [[hAtom]], [[hcalendar|hCalendar]], [[hcard|hCard]] and [[hreview|hReview]], is:

:<pre><abbr class="foo" title="YYYY-MM-DDTHH:MM:SS+ZZ:ZZ">Date Time</abbr></pre>

where foo is the semantic classname which is being applied to this date/time, the title of the <abbr> is an ISO 8601 date/time, with an appropriate level of specificity, and "Date Time" is a human-friendly representation of the same date/time.

An alternative, if you are using UTC-based timestamps, would be:

:<pre><abbr class="foo" title="YYYY-MM-DDTHH:MM:SSZ">Date Time</abbr></pre>

with a single "Z" as per [[iso-8601|ISO 8601]]

Ruby: An easy way to get this format from a DateTime is this:
:<pre>DateTime.now.to_s</pre>

== Profile of ISO8601 ==

Any [[microformat]] using the date-time-design pattern {{should}} use a profile of [[iso-8601|ISO8601]]. There are currently two widely used profiles which {{should}} be reused.

* RFC 3339
* [http://www.w3.org/TR/NOTE-datetime W3C Note on Datetimes]

==Accessibility issues==

Note: Some accessibility issues have been raised([http://www.webstandards.org/2007/04/27/haccessibility/]) with Datetime Design Pattern, and concerns that its use could breach WCAG accessibility guidelines, that are being addressed as part of the [[abbr-design-pattern-issues]] discussion. Possible change recommendations may follow after the accessibility testing is complete. The accessibility concerns are considerably lessened, even eliminated when using the [[date-design-pattern]], a subset of the [[datetime-design-pattern]].

== Discussion ==
This pattern is likely to be highly resuable.

--[[User:RyanKing]]

Can this not be viewed as a microformat in itself?

--[[User:DimitriGlazkov]]

It could, but inventing a microformat for the sake of inventing a microformat is against the microformat principles.
If there is a specific real world problem (and uses cases) that such an elemental microformat would solve, then it would be worth considering.

Until then it is best to keep the <abbr> datetime concept merely as a microformat design pattern, to be used in _actual_ microformats that have a demonstrated practical need.

-- [http://tantek.com/log/ Tantek]

Excerpt from #microformats Aug 18th. Please edit!

<pre>
Aug 18 15:16:14 <Tantek> DanC, what do you think of RFC3339?
Aug 18 15:17:14 <Tantek> ISO8601 subset
Aug 18 15:17:19 <DanC> Date and Time on the Internet: Timestamps http://www.ietf.org/rfc/rfc3339.txt
Aug 18 15:17:30 <DanC> Klyne is a good guy. I wonder if I talked with him about this.
Aug 18 15:17:32 <Tantek> compat with W3C-NOTE-DATETIME
Aug 18 15:17:50 <Tantek> compat with xsd:dateTime
Aug 18 15:17:57 <Tantek> it's a strict intersection subset
Aug 18 15:17:59 <DanC> I consider W3C-NOTE-DATETIME obsoleted by XML Schema datatype-- yeah.. xsd:dateTime
Aug 18 15:18:32 <Tantek> compare/contrast normatively using xsd:dateTime vs. RFC3339
Aug 18 15:18:41 <Tantek> note: Atom 1.0 chose RFC3339
Aug 18 15:18:50 <Tantek> i would like input from the microformats community on this
Aug 18 15:19:27 <DanC> in what context are you evaluating RFC 3339?
Aug 18 15:19:28 <jcgregorio> http://bitworking.org/news/Date_Constructs_in_the_Atom_Syndication_Format
Aug 18 15:21:24 <DanC> which microformat is the question coming from, Tantek ?
Aug 18 15:23:31 <DanC> " The grammar element time-second may have the value "60" at the end of
Aug 18 15:23:31 <DanC> months in which a leap second occurs" The XML Schema WG is in the 27th level of
leap-second-hell for the past few months, I gather.
Aug 18 15:24:21 <DanC> yeah... here's the scary bit: " Leap seconds cannot be predicted far into the
future. The
Aug 18 15:24:21 <DanC> International Earth Rotation Service publishes bulletins [IERS] that
Aug 18 15:24:21 <DanC> announce leap seconds with a few weeks' warning."
Aug 18 15:26:03 <Tantek> DanC, which microformats? any/all that use datetime fields.
Aug 18 15:26:36 <DanC> hard to give useful advice, then.
Aug 18 15:26:58 <DanC> I expect they'll use datetime fields for different things that have different
cost/benefit trade-offs
Aug 18 15:27:26 <DanC> do you know of any particular differences that matter to anybody?
Aug 18 15:56:43 <KragenSitaker> RFC3339 suggests -07:00, which seems like an improvement over -0700 anyway
Aug 18 15:56:49 <Tantek> Kragen, agreed
Aug 18 15:57:01 <Tantek> RFC3339 is certainly preferable to the ISO8601 subset in iCalendar
Aug 18 16:05:57 <DanC> Tantek's right, Kragen; iCalendar looks like it solves the local timezone
problem but doesn't.
Aug 18 16:06:14 <DanC> and it's true that there's no standard solution to the local timezone problem
Aug 18 16:06:39 <Tantek> so instead of appearing to solve the problem but not solving it, we chose to
provide the ability to *approximate* the local timezone using e.g. "-07:00"
Aug 18 16:06:49 <DanC> the simplest thing is to have people use Z time in hCalendar. But I gather
that's unacceptably unusable?
Aug 18 16:07:35 <Tantek> DanC, yes, the simplest thing is to have everyone use UTC Z
Aug 18 16:07:38 <Tantek> However
Aug 18 16:07:50 <Tantek> it is not *nearly* as usuable/verifiable
Aug 18 16:07:55 <Tantek> as -07:00 etc.
Aug 18 16:08:02 <Tantek> hence the decision to go with the latter
Aug 18 16:08:12 <Tantek> some degree of human verifiability is important here
Aug 18 16:14:21 <Tantek> DanC, my perception is that RFC3339 is a subset
Aug 18 16:17:00 <DanC> time-numoffset = ("+" / "-") time-hour ":" time-minute
Aug 18 16:17:34 <DanC> ok, then I can't see any differences. (modulo recent leap seconds issues that
may affect xsd:dateTime )
Aug 18 16:18:07 <Tantek> would be interesting to know why Atom 1.0 chose RFC3339 over xsd:dateTime
Aug 18 16:18:21 <Tantek> if there was a "real" reason or if it was arbitrary / coin-flip.
</pre>

Here's an exhaustive [http://www.imc.org/atom-syntax/mail-archive/msg13103.html comparison] from ndw. I think xsd:dateTime also allows unqualified local times, while RFC3339 allows only UTC with no known timezone (-00:00). In the end, Atompub followed the advice of [http://www.imc.org/atom-syntax/mail-archive/msg13244.html Sam Ruby] and [http://www.imc.org/atom-syntax/mail-archive/msg13248.html Scott Hollenbeck], our area director. Atom dates make some additional restrictions on RFC3339, such as uppercase T and Z characters for compatibility with xsd:dateTime, RFC3339, W3C-DTF, and ISO8601. --[http://franklinmint.fm Robert Sayre]

<pre>
Aug 18 16:18:43 <KragenSitaker> rfc3339 is pretty short.
Aug 18 16:19:36 <Tantek> DanC, BTW, which came first? REC for xsd:dateTime or RFC3339?
Aug 18 16:19:50 <DanC> RFC3339 is dated July 2002 ...
Aug 18 16:19:54 <KragenSitaker> Right --- and you might be able to understand xsd:dateTime without
reading all of xml schema, you wouldn't be confident of it
Aug 18 16:20:25 <DanC> W3C Recommendation 28 October 2004 ... but that's 2nd ed...
Aug 18 16:20:47 <DanC> W3C Recommendation 02 May 2001
Aug 18 16:22:10 <DanC> I don't see a BNF in http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#dateTime ...
Aug 18 16:22:43 <KragenSitaker> yeah, appendix D of the current xml schema datatypes document seems
a little scanty, actually
Aug 18 16:23:28 <DanC> ah... 2nd ed of http://www.w3.org/TR/xmlschema-2/#date is much more
explicit about syntax.
Aug 18 16:23:30 <KragenSitaker> it's 1100 words but still doesn't give any examples
Aug 18 16:23:35 <DanC> still, it's given in prose and not BNF
Aug 18 16:24:17 <KragenSitaker> sections 3.2.9 through 3.2.14 seem to be the relevant ones around #date
Aug 18 16:24:29 <KragenSitaker> which is another 2200 words
Aug 18 16:24:42 <DanC> wow... they changed the canonical form of date from always-Z to
timezone-allowed between 1st edition and 2nd edition
Aug 18 16:25:01 <Tantek> Kragen, DanC, these are very good analyses
Aug 18 16:25:21 <Tantek> could I ask you to summarize the pros/cons for each in a new section at
end of http://microformats.org/wiki/datetime-design-pattern
Aug 18 16:25:22 <Tantek> ?
Aug 18 16:25:58 <KragenSitaker> rfc 3339 is 4000 words, excluding the last two pages of boilerplate.
Aug 18 16:26:31 <KragenSitaker> so it's actually longer than the datetime-relevant parts of XSD but it
seems much more rigorous and clear
Aug 18 16:28:37 <DanC> my advice is: normatively cite both, and claim they specify the same
syntax, and let anybody who discovers otherwise send you a bug report
with a test case
Aug 18 16:29:12 <KragenSitaker> danc: nice hack
</pre>

The RFC3339 has a mandatory TIME portion of the DATE-TIME. Some vCard/iCalendar DATE-TIME stamps can omit the TIME. For instance, DTSTART, if that is a full day event, then you can omit the time. BDAY in vCard can be respresented by only a DATE. I like the idea of restricting the possible date formats, but i think that TIME should be optional, which it isn't in RFC3339. - [http://suda.co.uk/ brian suda]

RFC 3339 allows lowercase 't' and 'z' while XSD doesn't. Specifying RFC 3339 plus 'T' and 'Z' MUST be caps will make them the same. - [http://bitworking.org Joe Gregorio]

---

A few questions: asked by [[User:CharlesBelov|CharlesBelov]] 16:57, 24 Apr 2007 (PDT), answered by [[User:JamesCraig|JamesCraig]] on 15:58, 5 Jul 2007 (PDT).

# Would it make more sense for documenting the alternative codings pitting the abbr tag vs. other tags to be on this page? ''Answer: That documentation should go on the [[assistive-technology-abbr-results]] page.''
# Would using the title attribute of the abbr tag to encode the machine-readable date in fact cause a failure of WCAG 2.0 Accessibility? What about USA Section 508? It does appear to violate Technique for WCAG 2.0 [http://www.w3.org/TR/WCAG20-TECHS/#H28 H28: Providing definitions for abbreviations by using the abbr and acronym elements], although that is a supporting document and does not have the force of a guideline. ''Answer: Yes, it appears that is in violation of WCAG, 508, et al, so alternatives are being discussed on the [[assistive-technology-abbr-results]] page.''
# In order to maintain accessibility, would it make sense to enclose the machine-readable date in a span with a style of "display:none" instead of using the abbr tag? ''Answer: please refer to and add any suggestions to [[assistive-technology-abbr-results]].''
# For that matter, wouldn't you want to style such an abbr tag with text-decoration:none to hide that an abbr tag was used? Otherwise, visitors might cursor over the time, see the machine time, and be annoyed that their time was wasted or else be confused. And I don't think you can suppress the title from coming up if the human-readable time was inadvertently hovered. ''Answer: Microformats should not rely on CSS in order to work properly, but again, that discussion can be found here: [[assistive-technology-abbr-results]].''

== Code ==
The following regular expression (parsed VERBOSE) should break apart a datetime and cover many lightly broken cases seen in the wild. This has been tested under Python.

<pre><nowiki>
^
(?P<year>\d\d\d\d)
([-])?(?P<month>\d\d)
([-])?(?P<day>\d\d)
(
(T|\s+)
(?P<hour>\d\d)
(
([:])?(?P<minute>\d\d)
(
([:])?(?P<second>\d\d)
(
([.])?(?P<fraction>\d+)
)?
)?
)?
)?
(
(?P<tzzulu>Z)
|
(?P<tzoffset>[-+])
(?P<tzhour>\d\d)
([:])?(?P<tzminute>\d\d)
)?
$
</nowiki></pre>

== Other Proposals ==

=== strtime instructions as class names ===

Proposal by DavidLaban (alsuren on freenode) on 8 Jun 2008
It might be possible to have a slightly more readable/extensible/elegant format:
<pre><nowiki>
<span class="strtime format:_%d_%B_%Y_" > 16 March 1987 </span>
</nowiki></pre>
Notes:
# Underscores are used to replace whitespace, because otherwise the the formatting string will be split into an unordered set of class attributes by many parsers (thanks go to bogdanlazarsb and gsnedders on irc for explaining this to me).
# Some subset of the placeholders should be chosen from those which are supported by both python http://docs.python.org/lib/module-time.html and php http://uk3.php.net/manual/en/function.strftime.php
# A name for the class should be decided upon. strtime might not be the best name.
# Measures should be taken to avoid the format string accidentally conflicting with other valid classes (In the above example, I have prefixed it with the string "format:")
# It might be sensible (when parsing) to strip excess whitespace from the format string and contents. This is not done in this example.
# Example python code follows.

<pre><nowiki>
date = (1987,03,16,0,0,0,0,0,0)
format = " %d %B %Y "
# To encode:
classes = ["strtime"]
encoded_format = "format:" + format.replace(' ', '_')
classes.append(encoded_format)
content = time.strftime(format, birthday)
# ... dump classes and content into your document however you want

# To decode (assuming that you have managed to extract class and format from the document already):
if "strtime" in classes:
possible_formats = [ item for item in classes if item.startswith('format:') ]
assert len(possible_formats) == 1
format = possible_formats[0].strip('format:').replace('_', ' ')
date = time.strptime(content, format)
</nowiki></pre>

==== problems with strtime proposal ====

# Possible abuse of the class attribute. microformats limit the use of the class attribute to marking up additional semantics about the data, not for (potentially) arbitrary processing/programming instructions
#* HTML 4.01 Recommendation [http://www.w3.org/TR/REC-html40/struct/global.html#adef-class defines] the <code>class</code> attribute as being "for general purpose processing by user agents". [[User:TobyInk|TobyInk]] 13:21, 8 Jun 2008 (PDT)
# Requires authors to think like programmers. The larger problem is that the proposal asks web authors to think like programmers, which severely limits the number of web authors which will be able to use the technique, since the vast majority of web authors are ''not'' programmers and have never heard of "strtime", whereas most authors (even people) on the web have seen dates like 2005-06-20 and easily understand what they mean.

In general, any publishing method that requires the author to think like a programmer is a non-starter. It is a much more of a barrier than simply using ISO8601/RFC3339, and that barrier is a far worse tradeoff than the duplication / DRY violation compromise.
[[User:Tantek|Tantek]] 09:52, 8 Jun 2008 (PDT)

* Another problem: if %A/%a/%B/%b are allowed, this raises potential problems with internationalisation. Will parsers be required to understand the names and abbreviations for days and months in potentially hundreds of different languages? [[User:TobyInk|TobyInk]] 14:09, 8 Jun 2008 (PDT)

=== Machine-data in class===
The BBC ([http://microformats.org/discuss/mail/microformats-dev/2008-June/000552.html uf-dev archive, 20/06/08, "Using class for non-human data"]) has proposed as an alternative to the empty span and title solution to use the class name in the following way:
<pre><nowiki>
<span class="dtstart data-20051010T10:10:10-0100">10 o'clock on the 10th</span>
</nowiki></pre>
Pros:
* Allows data to be represented in a "non-harmful" way. Will not be read aloud by screenreaders or seen as tooltips.
* Minimises mark-up used.
* Arguably more semantic than use of "title" attribute for non-human data.

Cons:
* data in the class attribute has already been discussed numerous times in the mailing list over the years and rejected and documented as an [[anti-pattern]] - captured [http://microformats.org/wiki?title=anti-patterns&diff=24271&oldid=24270 on the wiki this past January 2008].
* Possible misuse of class attribute, although as noted previously, the HTML spec states "for general purpose processing by user agents".
* The class attribute has been adopted by the broader web design community to "subclass" element semantics, and to layer additional semantics. To date, microformats has followed this existing practice developed by modern web designers ("paving the cow-paths"). This use of class for data is outside all current practices.

Discussion:
* This proposal smells icky, but I can't quite put my finger on why. Considered objectively, it does seem to be the least harmful solution proposed so far. [[User:TobyInk|TobyInk]] 06:06, 21 Jun 2008 (PDT)
* I really like it, especially given the HTML4 spec gives this as an IMO perfectly valid use (on both id and class, with the following examples given in the id section: "identifying fields when extracting data from HTML pages into a database, translating HTML documents into other formats, etc."). Clean and simple. [[User:Dracos|Dracos]] 03:53, 23 Jun 2008 (PDT)
* I suggest dropping the redundant 'data-' prefix, unless someone can suggest a feasible case with two time-stamps requiring different prefixes. The proposal then becomes [http://www.robertnyman.com/2008/04/28/do-we-really-need-microformats/#comment-263408 one I've made before] [[User:AshSearle|AshSearle]]
** Valid class names cannot begin with a number, so a date needs some sort of letter prefix. It's sensible to make this prefix meaningful and reusable in some way. [[User:Phae|Phae]]
*** They can't in CSS, but they can in (X)HTML. http://examples.tobyinkster.co.uk/numeric-classes.html [[User:TobyInk|TobyInk]] 06:53, 24 Jun 2008 (PDT)
**** Creating classes in HTML that can't be referenced in CSS is a bad thing. Using colons and starting with numbers fall into that category. http://www.w3.org/TR/CSS21/syndata.html#characters Also, replacing whitespace with underscores breaks the ISO compatibility, which sorta defeats the whole point of using existing standards. Finally the class names are unordered, so trying to use them in a series is a bad idea. --[[User:Atamido|Atamido]] 11:43, 30 Jul 2008 (PDT)
***** They can be referenced in CSS, just not using the "dot notation". They can be referenced using attribute selectors, which are supported in all modern browsers (but not IE6). [[User:TobyInk|TobyInk]] 13:21, 30 Jul 2008 (PDT)
****** They could also be referenced by escaping the characters, but that still excludes >99% of current use cases. I'd wager that most authors don't even know about the limitations and would run into issues in implementation. --[[User:Atamido|Atamido]] 13:47, 30 Jul 2008 (PDT)
***** I don't think the proposal relies on classes being in any particular order. Even if it did, I don't know of any DOM implementations which do not provide the contents of the class attribute in their original order. [[User:TobyInk|TobyInk]] 13:21, 30 Jul 2008 (PDT)
** Not to advocate too strongly for designing for parsers (generally a bad idea), *but* having a 'data-' prefix on a class name would make identifying data orders of magnitude easier for parsing. Otherwise, how do we know what's data and what's just another class name for some other purpose? [[User:DrewMcLellan|Drew]]
** A 'data-' prefix would help authors tasked with maintaining or reviewing a page to understand the purpose of a class name that may have been applied by another author. The data prefix communicates very simply that the class name is precisely that, data. Therefore the value is less likely to be accidentally removed or changed, making for a more robust design. [[User:DrewMcLellan|Drew]]
*** I concede - regardless of whether it's valid (X)HTML / CSS - a prefix is needed to distinguish data values from genuine content. ISO 8601 allows date-time to be as simple as "2004", which could easily be misinterpreted. e.g. if a CMS outputs product model numbers into the class attribute for some other purpose. --[[User:AshSearle|AshSearle]] 01:42, 25 Jun 2008 (PDT)
*** Using <code>data-</code> as the prefix here is undesirable, as it now conflicts with HTML5's proposed <code>-data</code> prefix on attributes. It's undesirable to set ourselves up for future confusion with our own conflicting specification of ‘a data prefix’. A different prefix should be considered. See: [http://www.w3.org/html/wg/html5/#custom HTML5 Editors Draft: Embedding Custom Non-Visible Data] —[[User:BenWard|BenWard]] 07:34, 16 Jul 2008 (PDT)
* -1 [[User:Tantek|Tantek]]. I'm vehemently opposed to putting data in the class attribute. We ''must'' find better alternatives. We must not go down the path of invisible (dark) (meta)data - IMHO that [[principle]] is inviolable for microformats.
** [[User:JakeArchibald|JakeArchibald]] If you're so opposed, it'd be useful to see some justification.
*** See above cons. Already discussed/rejected many times in the history of microformats discussions. In short, quit wasting time on old ground. Abuses class attribute, or if you prefer, introduces a *new* use of the class attribute, unlike microformats to-date which have simply made use of a well established semantic of the class attribute. And worst of all, completely violates the visible data [[principle]]. Rejectable on that alone.
**** The fact that something has been discussed and rejected before is not sufficient grounds for dismissing it out of hand once additional research and thinking has taken place. The <abbr> datetime pattern arguably abused the title attribute and introduced a new use of the title attribute. In the example given (<code><nowiki><span class="dtstart data-20051010T10:10:10-0100">10 o'clock on the 10th</span></nowiki></code>), the data is presented as "10 o'clock on the 10th" - very visible. Yes, of course, it's possible to abuse this proposed pattern, and hide the data, but the same can be said of the abbr pattern or even the class pattern given CSS's display:none property. Experience shows that in most cases, people ''won't'' abuse the pattern to hide data, as they actually ''want'' to show the data on their pages. [[User:TobyInk|TobyInk]] 13:52, 24 Jun 2008 (PDT)
**** It's not an abuse of the class attribute according to the HTML spec. as I read it. Whereas using title for non-human data is (the spec says audio agents may read it aloud, for example). If it's a new use, it's one the writers of HTML4 considered, so it wasn't new to them. [[User:Dracos|Dracos]] 03:38, 25 Jun 2008 (PDT)
** Relevant princeples are 'humans first, machines second', and 'visible data is ''better'''. These are ''preferences'', not inviolable principles. Besides, the existing datetime spec doesn't adhere to these principles anyway: prioritising humans first, <code><nowiki>let's discuss this at the next meeting</nowiki></code> should be marked up as <code><nowiki>let's discuss this at the <abbr title="28th June 2008 at 3:15pm">next meeting</nowiki></code>. There's a conflict between human- and machine-readable dates. It makes more sense to 'hide' the machine-readable data in the only attribute available to us: <code>class</code>. --[[User:AshSearle|AshSearle]] 03:02, 25 Jun 2008 (PDT)
*** Indeed - by their nature, ''principles'' are ''generalisations'', and while broadly useful, usually have exceptions. After experience, the microformats community is beginning to see some of these. Human vs machine dates is the one gathering the most interest at the moment, largely thanks to <abbr class="help" style="border-bottom:1px dotted" title="the Web Standards Project">WaSP</abbr> and <span class="help" style="border-bottom:1px dotted" title="the BBC">auntie</span>, but I think other properties which will probably emerge as exceptions to the general microformats principles are hReview's <code>type</code> property, and the its namesake subproperty for hCard's <code>tel</code>, <code>email</code> and <code>adr</code> (and <code>label</code>?) properties. [[User:TobyInk|TobyInk]] 12:51, 25 Jun 2008 (PDT)

==== Experimental Parser Support ====

[http://buzzword.org.uk/cognition/ Cognition 0.1 alpha 10] will include experimental support for this pattern, and the [http://srv.buzzword.org.uk Cognition web service] already does. Notes:
* Support is ''opt-in''. Publishers must explicitly request support for the pattern, by including a [[profile-uris|profile URI]] of <code><nowiki>http://purl.org/uF/pattern-data-class/1</nowiki></code> in their document head.
* Support is not limited to date-time properties, but any microformat properties.
* data-X classes must use percent-encoding to encode spaces and other characters not allowed in class names.
* The data-X class must be found on the same element as the microformat property class. That is, you cannot use: <pre><nowiki><span class="dtstart"><span class="data-20051010T10:10:10-0100">10 o'clock</span></span></nowiki></pre>
<ul><li>Multiple data-X classes may occur on the same element. When these are found, the longest string is used. This allows for: <pre><nowiki><span class="dtstart data-2005 data-200510 data-20051010">The 10th</span></nowiki></pre> which may be useful for styling or other non-microformat purposes.</li>
<li>Can be combined with value excerpting. e.g. <pre><nowiki>
<p class="dtstart">
The concert will be held on
<span class="value data-20080804">the 4th of August</span>
starting at
<span class="value data-T193000">7:30pm precisely</span>.
</p>
</nowiki></pre></li></ul>

=== date and time separation using value excerption ===

==== summary ====
By specifying a more precise parsing of the use of "value" excerption inside all datetime properties (e.g. dtstart, dtend, published, updated etc.), dates and times can be marked up separately, thus reducing/minimizing (and potentially eliminating) the readability issues that come with compound ISO8601 datetimes.

==== introductory example ====
The sentence:

<pre><nowiki>
The weekly dinner is tonight at 6:30pm.
</nowiki></pre>

would be marked up as:

<pre><nowiki>
The weekly dinner is <span class="dtstart"><abbr class="value" title="2008-06-24">tonight</abbr>
at <abbr class="value" title="18:30">6:30pm</abbr></span>.
</nowiki></pre>

==== advantages ====
* re-uses the readable [[abbr-date-pattern]]
* identifies a similarly readable abbr-time-pattern.
* minimizes DRY violation distance, keeps machine data on exactly the same element as the respective human data
** even better than [[abbr-datetime-pattern]] does, which, in practice from experience often required specifying the date in machine readable form on the human readable time (separate from the human readable date).
* introduces no new class names - [[principle]] of minimal invention
* introduces no new use of the class attribute - principle of minimal invention again
* introduces no new syntax ([[datetime-design-pattern#problems_with_strtime_proposal|see above]] about any publishing method that requires the author to think like a programmer being a non-starter, and introducing new syntax almost always requires authors to think like programmers).
* and most importantly, introduces no dark data.

==== issues ====
Some potential issues were raised in IRC, and it helps to document/resolve them so that they are not brought up repeatedly.
* [[http://rbach.priv.at/Microformats/IRC/2008-06-24#T163114 Does this sufficiently address the concerns raised with the current use of abbr-pattern?]]
*# The [[abbr-date-pattern]], as documented and explained by [[User:Adactio|Jeremy Keith]] is just fine (in contrast to the [[abbr-datetime-pattern]]).
*# Similar to the [[abbr-date-pattern]], this proposal implies/introduces the abbr-time-pattern, which is similarly acceptable.
*# In addition, as long there is incremental improvement, we are making progress. It is more important to take small steps that we know will help some things, rather than try to take a big step that is more risky in the attempt to help more but may not actually do so (as most big changes don't), therefore "sufficiently" is a flawed way of evaluating incremental fixes.
* Exposes data through tooltips. Separating into 2008-06-07 and 18:03 improves the ability for humans to consume the data, but still exposes data through tooltips and speech in formats that the publisher did not choose to use. --[[User:BenWard|BenWard]] 04:52, 25 Jun 2008 (PDT)
*# This is a feature, not a bug. By making the duplicated data at least *somewhat* visible (rather than fully invisible), effective data quality is increased due to the fact that the probability of the ISO8601 and locale-specific data getting out-of-sync is reduced because of the increased visibility (and therefore the increased inspectability and more eye-balls looking at/for problems effect).
*# Workaround: if a site publisher wishes to customize the presentation of tooltips, they can do so with a nested span with title.
*#* That proposes extraneous mark-up maintain some publisher's wish not to have a tool-tip in the first place. I object to a microformat pattern requiring an immediate work-around to meet publisher's desires. It goes against ‘Humans first…’. --[[User:BenWard|BenWard]] 09:09, 30 Jun 2008 (PDT)
*#*# Additional markup has nothing to do with "Humans first".
*#*# Additional markup to work-around minor issues (e.g. CSS, cross-browser compatibility, etc.) is a well accepted modern web design practice. It's not ideal, but it is both accepted and widely practiced. With the use of <code><span></code> and <code><div></code> elements, it's also semantically neutral, therefore not a problem from that perspective either.
*#*# Finally, it should not be our goal to try to satisfy *every* publisher, for that would make every microformat beholden to every publisher and contort the design of microformats in really poor ways. We must accept that not all publishers will adopt all microformats and that is ok. Our goal to incrementally increase the number of publishers that adopt microformats, not to try to satisfy each and every one.
* Semantic misuses of ABBR. That ‘tonight’ is ever a textual, human abbreviation of ‘2008-06-24’ is not accepted.
*# Semantic stretch not misuse. It is a semantic abbreviation rather than a purely syntactical (character shortening) abbreviation, but it is an abbreviation in context nonetheless. Though this may stretch what may be commonly expected as an "abbreviation", the HTML4 spec does seem to allow some flexibility here ([http://www.w3.org/TR/html401/struct/text.html#h-9.2.1 HTML 4.01 9.2.1 Phrase elements]).
* Maintaining proper sentences with the expanded form. It is not always possible to use this mark-up and maintain proper sentences with the expanded form. e.g. <code>it's my <abbr class="bday" title="2005-06-20">birthday today</abbr>!</code> becomes ‘it's my 2005-06-20!’. And thus audio rendition of such titles can be nonsensical - "The weekly dinner is two thousand and eight dash zero six dash twenty four at eighteen thirty."
*# This can and should be addressed by improving authoring examples so that practices improve with experience.
* Publishing practices and desires show us that authors are not willing to compromise the semantics of abbr. [[User:Phae|Phae]] 04:30, 27 Jun 2008 (PDT)
*# Without specific citations of which authors and what specific issues they have, we are unable to address their issues.
*# See also above - not our goal to satisfy *every* publisher, but rather to incrementally satisfy more and more. We must accept that there may be some authors we are unable to satisfy in the immediate/short-term.
* [[http://rbach.priv.at/Microformats/IRC/2008-06-24#T163435 That's getting pretty complicated]]
** Much less complicated than inventing yet another syntax ( " { ... } " ???? ) that web authors would have to learn.
*** But it's all in one place, rather than spreading it out.
**** The spreading it out is what current content publishing practices do already! It is much more important to map the machine data as close to the existing publishing practice as possible, than to try to "put it all in one place". The "put it all in one place" way of thinking is why people ended up sticking so much invisible metadata in the head of the document, which we know fails.

==== content requirements ====
Some requirements which enhance both human readability, ''and'' machine parsability (best of both) :
* date value excerpts MUST use hyphen separators. E.g. 2008-06-24. Not ok:20080624.
* time value excerpts MUST use colon separators (seconds optional, implied :00 if absent). E.g. 18:30 or 18:30:00. Not ok:183000.
* timezone value excerpts MUST use leading plus or minus and NO colon separator. E.g. -0700. Not ok:-07:00.

==== derivation ====
It's important to document the derivation/background of a brainstorm/proposal as it allows others to see some of the thinking that went into it, and avoid having to rediscuss alternatives already considered, and helps provide understanding as to why aspects of the design are as they are.
===== example with datetime =====
Here is a short code example:
<pre><nowiki>
the weekly dinner is tonight at <span class="dtstart">2008-06-24T18:30</span>
</nowiki></pre>
===== example with abbr datetime =====
However that's not the easiest to read, nor do most people publish that as human visible text, so per the abbr-datetime pattern:
<pre><nowiki>
the weekly dinner is tonight at <abbr class="dtstart" title="2008-06-24T18:30">6:30pm</abbr>
</nowiki></pre>

which has raised two issues:
# When "2008-06-24T18:30" is inspected by a human reading a tooltip, or spoken by a screen reader, it's not the most understandable thing (precise citation needed, perhaps an mp3 with screen reader used version info).
# There is a non-local violation of DRY (which IMHO is a worse problem, as it leads to worse data quality -[[User:Tantek|Tantek]]). That is, the "date" information is now not only in the text twice (as it was before), but those two instances of the date information are not on the same element, which makes it worse. That is, "tonight" is in the prose, ''outside'' of the element with the precise date "2008-06-24".

In analysis of examples of event information on the web, the date and time are often published in separate elements, often for display purposes.

Thus it is this existing content publishing practice which leads to this brainstorm proposal, to essentially to introduce a date and time value excerption longhand.

(Initially [http://rbach.priv.at/Microformats/IRC/2008-06-21#T181634 Tantek's idea that he bounced off Jeremy Keith] ([http://rbach.priv.at/Microformats/IRC/2008-06-24#T124652 similar idea conceived by Drew independently]) was to [http://rbach.priv.at/Microformats/IRC/2008-06-24#T161819 introduce new classes "datevalue", "timevalue"] and "tzvalue" for this purpose, but [http://rbach.priv.at/Microformats/IRC/2008-06-24#T171603 Bob Jonkman pointed out] that HTML5's time parsing algorithm enables a single <nowiki><time></nowiki> element to contain dates or times (with or without timezone) without having to explicitly say whether the value contains dates or times (with or without timezone). [http://rbach.priv.at/Microformats/IRC/2008-06-24#T171723 Bob then proposed] that thus all was needed was a single new "datetime" class name. This was the key realization that allowed minimal invention. Tantek pointed out that since from the type of property we already know it is a datetime, [http://rbach.priv.at/Microformats/IRC/2008-06-24#T171835 there was no need for even one new class name], that we could simply re-use "value" excerption, and simply more precisely specify the semantics/parsing in the case of datetime properties.)

===== example with new date and time value excerpts =====
Thus we markup the date and time separately, as value excerpts, using the [[abbr-date-pattern]] and an implied parallel abbr-time-pattern:

<pre><nowiki>
The weekly dinner is <span class="dtstart"><abbr class="value" title="2008-06-24">tonight</abbr>
at <abbr class="value" title="18:30">6:30pm</abbr></span>.
</nowiki></pre>

===== separate subtrees =====
The proposal also allows setting the date and time in separate element subtrees as well, which may be necessary for some document structures:

<pre><nowiki>
the weekly dinner is <span class="dtstart"><abbr class="value" title="2008-06-24">tonight</abbr></span>
at <span class="dtstart"><abbr class="value" title="18:30">6:30pm</abbr></span>.
</nowiki></pre>

Note the two instances of dtstart, one of which sets the date for the dtstart, and the other of which sets the time.

The idea being, when a parser sees a datetime property (e.g. dtstart) with a value excerpt, that it only "set" the component of its full value that is specified by the value excerpt (e.g. the date), and that if lacking a complete datetime, it continue to parse additional instances of that datetime property for the remaining component(s) (e.g. the time).

Of course this only works for singular properties, but fortunately all instances of datetime properties so far are singular, so this works.
* hCard's <code>rev</code> is plural. [[User:TobyInk|TobyInk]]
** can someone give a reference to this being the case? The RFC says "The value distinguishes the current revision of the information in this vCard for other renditions of the information." Does it make sense to have multiple REV dates in a single vCard?
*** The RFC is ambiguous as usual, but a contact card could conceivably have had several changes made to it, with a <code>rev</code> for each. ("Change logs" are fairly common on the web.) The [[hcard|hCard spec]] is fairly specific about which properties are [[hcard#Singular_vs._Plural_Properties|singular]] and which are not, and <code>rev</code> is not included in the list of singular properties.

===== reusing date data for multiple datetime properties =====
This also provides a *very* convenient way to re-use the same date information for start and end, e.g. expanding the example:

<pre><nowiki>
the weekly dinner is <span class="dtstart dtend"><abbr class="value" title="2008-06-24">tonight</abbr></span>
from <span class="dtstart"><abbr class="value" title="18:30">6:30</abbr></span> -
<span class="dtend"><abbr class="value" title="20:30">8:30pm</abbr></span>.
</nowiki></pre>

Note what just happened. we just eliminated another duplication of date information by reusing the start *date* information for the end *date* information and *only* specifying the end *time* information separately for the two properties.

Reducing the duplication (or triplication) of such data helps to reduce the chances of (even inadvertent) data corruption/drift/divergence among any duplicates.

===== time zones =====
There are a few choices for timezones.
# Simply include the time zone information as part of the time "value". <br /> E.g. <code><nowiki><abbr class="value" title="18:30-0700">6:30pm</abbr></nowiki></code>
# Or use another value excerpt for the timezone (was: <del>introduce the class name "tzvalue"</del>) <br /> E.g. <code><nowiki><abbr class="value" title="18:30">6:30pm</abbr> <abbr class="value" title="-0700">PDT</abbr></nowiki></code>
# Or allow both and let web authors decide. This is the current leaning.
#* if web authors want to specify timezone as part of the time (first example above), they can,
#* or if web authors visibly publish the timezone separately (second example above), then they can mark that up.
#* or if web authors wish to omit timezone information, they can do so as well, as most do today. In practice this works fine, as it creates a "floating" time which works fine in far more than the 80/20.

(more to come, documenting [http://rbach.priv.at/Microformats/IRC/2008-06-24#T161740 from IRC logs])

==== discussion ====
Opening up a discussion section even though documentation [http://rbach.priv.at/Microformats/IRC/2008-06-24#T161740 from IRC logs] is still in progress. :)

* regarding the [[datetime-design-pattern#advantages|advantage]] of "and most importantly, introduces no dark data."
** "Dark data" is sometimes what publishers *want* to publish. To use the example of TV schedules which kick started the renewed discussion in this area, publishers will often not want to display the date. For instance, if a page entitled "Tomorrow's TV" and containing 300 different programmes marked up with <code>dtstart</code>, it is superfluous to explicitly display the date for each one. With this proposed solution the [[include|include pattern]] could be used to include the date into each vevent, but a visible link to the date on each programme would simply be confusing. Sometimes it just makes sense to hide some of the information you're publishing as a microformat - because the information you want to make explicit to parsers can be inferred from context by humans, or is more appropriately displayed at a different level of granularity for machines and humans. [[User:TobyInk|TobyInk]] 14:26, 24 Jun 2008 (PDT)
*** It doesn't matter whether publishers *want* to publish dark data or not. Invisible data always leads to poorer quality data. Publishers publish all kinds of invisible metadata in the heads of documents etc. because they want to, but their desire doesn't stop the data from becoming obsolete, diverging from the actual visible data etc. The quality of the data matters more than any publishers wish(es) of publishing in a specific format, or in a hidden way. In the example you gave, using the include pattern in that way would not result in any visible links, but merely empty include anchors. It never makes any sense to actually hide "some of the information you're publishing as a microformat", because historically that always results in some loss of data quality over time and thus the microformats [[principle]] of visible data instead of invisible metadata. [[User:Tantek|Tantek]] 14:32, 24 Jun 2008 (PDT)
**** All microformats hide ''some'' data. In the example <code><nowiki><span class="tel">01632 960123</span></nowiki></code>, the information that the long string of numbers represents a telephone number is invisible. And making it visible (<code><nowiki>Tel: <span class="tel">01632 960123</span></nowiki></code>) violates DRY. It's just a matter of where to draw the line.
***** That statement makes the mistake of conflating *type* data and *content* data. "tel" is not content data, just as <nowiki><p></nowiki> is not content data. It's markup, indicating the type of the data. Markup (type data) being invisible to the user has worked just fine. Content (content data) being invisible to the user is the problem of dark data. Or rather, if you think that everything is data, then you really should be spending time developing in a system that is built on that assumption, e.g. RDF, rather than microformats, which are built on HTML, and the clear separation of type of data (HTML elements, microformats properties) and content data (inner text, text attribute values).
****** My point is that there isn't a ''distinction'' between the two, but a ''continuum''. The choice of where to draw the line is never a clear one and always somewhat arbitrary. The vCard standard could quite easily have ended up with separate "TEL", "FAX" and "CELL" properties, in which case hCard would have ended up with <code><nowiki><foo class="tel"></nowiki></code>, <code><nowiki><bar class="fax"></nowiki></code> and <code><nowiki><baz class="cell"></nowiki></code>. Going the other way, they could have stored e-mail addresses as mailto: URLs, and then hCard would have <code><nowiki><a class="url" href="mailto:quux@example.com"></nowiki></code>. They chose the way they did, and as a result in hCard the distinction between a mailto: URI and an http: URI is largely invisible (in most circumstances only obvious by looking at the status bar when hovering), but the distinction between a telephone number and a fax number is visible. But that wasn't the only possible (nor the only reasonable) outcome.

=== HTML 5 <code><time></code> Element ===

[http://microformats.org/wiki/hcalendar-issues#html5-time-element See hCalendar issues]

=== Plain Old English alternative to ISO date ===

Example (in English):

<pre>
<abbr title="January 25th, 2008" class="dstart" lang="en-us">1/25</abbr>
</pre>

<pre>
<span class="dstart">January 25th, 2008</span>
</pre>

If <code>lang="en-us"</code>, the format of the date used in the <code>title</code> attribute must conform to [http://www.ego4u.com/en/cram-up/vocabulary/date/written dates writing rules in American English].

Example (in French):

<pre>
<abbr title="25 Janvier 2008" class="dstart" lang="fr">25/1</abbr>
</pre>

If <code>lang="fr"</code>, the format of the date used in the <code>title</code> attribute must conform to date writing rules in French.

====Benefits====

* Human-hearable: should work nicely with screen readers (to be tested).
* Human-readable
* Compliance with semantics of abbr.
* Very easy to use by HTML human authors.
* DRY compliant if HTML human authors are willing to write in correct English

====Discussion====

* Locale-specific parsing logic.
* Not all cultures use the same calendar — Dan Brickley
* There are situations where markup clues used for localisation might be misleading, such as people using microformats in a post on a site they do not themselves run that may even be in a different country. (a shared blogging site that allows html tags in posts would be a good example here) — Michael MD
** Couldn't the person or tool adding the microformat annotation also add a lang attribute at the same time? — Benjamin Hawkes-Lewis
* Cognition already supports this as a last ditch attempt at parsing dates - but I wouldn't recommend it get adopted widely. It's too unreliable; too much work to deal with internationalisation; too much work full-stop in languages that don't provide a handy library that takes care of most of the work. — [[User:TobyInk]]
** I don't think we need to support all locales at once. I don't know in how many written languages BBC publishes in, but it might be that supporting en-uk and en-us might be enough for a start. Also, one can imagine that Microformats tools could focus on the most common written languages and then expose hooks for others to implement support for other locales. — Guillaume Lebleu
** What are our priorities? Making programmers' life easier or making content authors and content readers' life easier? — Guillaume Lebleu
*** In Australia dd/mm/yyyy is commonly used, but a significant minority of sites in Australia use US-style mm/dd/yyyy because it is the default setting in their CMS. How would a parser be able to tell which part is the day and which is the month? Getting it wrong would be worse than not getting it at all! Until the use of ambiguous formats can be ''wiped out'' we ''will'' need a version for machines! — Michael MD
*** problem which hasn't been raised with regards to this proposal is that even though you are proposing a fixed date format, because it *looks* like natural language, authors will assume that it *is* natural language, and simply start including dates in whatever format they like. Then you get an NLP "arms race" between publishers and parsers. If you don't believe that that will happen, take a look at what happened with RFC 822 dates, which are simply a mess. — [[User:TobyInk]]
**** Very true the more you make the date look like natural language, the less it looks like a fixed format. I really don't want us to get involved in any form of NLP, it just would not work. I think it was Mike who said that dates have to be parsed correctly, no level of error is acceptable. I don't want to travel to an event on the wrong day because a parser got the date wrong — Glenn Jones

====Notes====

* Could work alongside with the existing [[datetime-design-pattern]]: if ISO date parsing fails, try parsing the title as a human-readable plain old English/French/... date according to the locale.

===<code><object></code> element to represent dates===

* Re-raised by George Brocklehurst on June 25th 2008.

The idea was to do something like this:

<pre><code><object data="20050125">January 25</object></code></pre>

* From what Tantek [http://tantek.com/log/2005/01.html said on his blog] , the main reason for not using objects was that they were not well supported in Safari. However, Safari's object support is now much improved: fallbacks are supported and display:inline and intrinsic sizing will work correctly. Safari 2.0.2, which came out in November 2005, was the first version to [http://webkit.org/blog/32/webkit-fixes-in-safari-202-mac-os-x-1043/ contain these improvements]. — George Brocklehurst
* The following appears to be well behaved inline in Safari 2.04 and 3.1.1, Firefox 1, 1.5, 2 and 3, and Opera 7, 8 and 9: <code><object class="dtstart" data="data://20080712"></object></code>. Test case: http://pastie.org/224023 — Ben Ward
** IE 6, 7 and the beta version of IE 8 all visibly render the object element as a small box, similar to the way they would render a missing image: http://georgebrock.com/misc/object-in-ie.png — George Brocklehurst
** Absolute URIs can't start with a number, but relative ones can - and the data attribute is permitted to contain relative URIs. [Don't need to use data:// URI) — Toby A Inkster
* Could also look at <code><object class="dtstart"><param name="value" value="20050125" />January 25</object></code> — Scott Reynen
* 1. The purpose of the <object> element is to allow the browser to run an external application for a non-native data type (e.g., Java applet). See: http://www.w3.org/TR/REC-html40/struct/objects.html#h-13.3. Object is not the right way to go in this case. — Sarven Capadisli

== See Also ==

* [[Main_Page#Design_Patterns|All microformat design patterns]]
* [[abbr-design-pattern]] is used by [[datetime-design-pattern]]
* [[date-design-pattern]] is a subset of [[datetime-design-pattern]]
* HTML 4.01 definition of <code><[http://www.w3.org/TR/REC-html40/struct/text.html#edef-ABBR abbr]></code> element
* RFC [http://www.faqs.org/rfcs/rfc3339.html 3339]: Date and Time on the Internet: Timestamps
* W3C: [http://www.w3.org/TR/NOTE-datetime Note on Datetimes]
* Markus Kuhn: [http://www.cl.cam.ac.uk/~mgk25/iso-time.html A summary of the international standard date and time notation]
* Wikipedia: [http://en.wikipedia.org/wiki/ISO_8601 ISO 8601]

datetime-design-pattern

2008-07-30T18:43:45Z

Atamido: /* Machine-data in class */

<h1> Datetime Design Pattern </h1>
This is a page for exploring a datetime design pattern.

{{TOC-right}}

== Purpose ==
* Use the [[datetime-design-pattern]] to make datetimes that are human readable also formally machine readable.

== Practical Need ==
* This design pattern arose as a result of solving the practical need for human readable dates for [[hcalendar|hCalendar]].

== How to use it ==
* enclose the human-friendly datetime that you want to make machine readable with <code><abbr></code>
* as per the [[class-design-pattern]], add the appropriate <code>class</code> attribute to the <code>abbr</code> element
* add a <code>title</code> attribute to the <code>abbr</code> element with the machine readable [[iso-8601|ISO8601]] datetime or date as the value

==Current uses==

The pattern, which is now available as part of [[hAtom]], [[hcalendar|hCalendar]], [[hcard|hCard]] and [[hreview|hReview]], is:

:<pre><abbr class="foo" title="YYYY-MM-DDTHH:MM:SS+ZZ:ZZ">Date Time</abbr></pre>

where foo is the semantic classname which is being applied to this date/time, the title of the <abbr> is an ISO 8601 date/time, with an appropriate level of specificity, and "Date Time" is a human-friendly representation of the same date/time.

An alternative, if you are using UTC-based timestamps, would be:

:<pre><abbr class="foo" title="YYYY-MM-DDTHH:MM:SSZ">Date Time</abbr></pre>

with a single "Z" as per [[iso-8601|ISO 8601]]

Ruby: An easy way to get this format from a DateTime is this:
:<pre>DateTime.now.to_s</pre>

== Profile of ISO8601 ==

Any [[microformat]] using the date-time-design pattern {{should}} use a profile of [[iso-8601|ISO8601]]. There are currently two widely used profiles which {{should}} be reused.

* RFC 3339
* [http://www.w3.org/TR/NOTE-datetime W3C Note on Datetimes]

==Accessibility issues==

Note: Some accessibility issues have been raised([http://www.webstandards.org/2007/04/27/haccessibility/]) with Datetime Design Pattern, and concerns that its use could breach WCAG accessibility guidelines, that are being addressed as part of the [[abbr-design-pattern-issues]] discussion. Possible change recommendations may follow after the accessibility testing is complete. The accessibility concerns are considerably lessened, even eliminated when using the [[date-design-pattern]], a subset of the [[datetime-design-pattern]].

== Discussion ==
This pattern is likely to be highly resuable.

--[[User:RyanKing]]

Can this not be viewed as a microformat in itself?

--[[User:DimitriGlazkov]]

It could, but inventing a microformat for the sake of inventing a microformat is against the microformat principles.
If there is a specific real world problem (and uses cases) that such an elemental microformat would solve, then it would be worth considering.

Until then it is best to keep the <abbr> datetime concept merely as a microformat design pattern, to be used in _actual_ microformats that have a demonstrated practical need.

-- [http://tantek.com/log/ Tantek]

Excerpt from #microformats Aug 18th. Please edit!

<pre>
Aug 18 15:16:14 <Tantek> DanC, what do you think of RFC3339?
Aug 18 15:17:14 <Tantek> ISO8601 subset
Aug 18 15:17:19 <DanC> Date and Time on the Internet: Timestamps http://www.ietf.org/rfc/rfc3339.txt
Aug 18 15:17:30 <DanC> Klyne is a good guy. I wonder if I talked with him about this.
Aug 18 15:17:32 <Tantek> compat with W3C-NOTE-DATETIME
Aug 18 15:17:50 <Tantek> compat with xsd:dateTime
Aug 18 15:17:57 <Tantek> it's a strict intersection subset
Aug 18 15:17:59 <DanC> I consider W3C-NOTE-DATETIME obsoleted by XML Schema datatype-- yeah.. xsd:dateTime
Aug 18 15:18:32 <Tantek> compare/contrast normatively using xsd:dateTime vs. RFC3339
Aug 18 15:18:41 <Tantek> note: Atom 1.0 chose RFC3339
Aug 18 15:18:50 <Tantek> i would like input from the microformats community on this
Aug 18 15:19:27 <DanC> in what context are you evaluating RFC 3339?
Aug 18 15:19:28 <jcgregorio> http://bitworking.org/news/Date_Constructs_in_the_Atom_Syndication_Format
Aug 18 15:21:24 <DanC> which microformat is the question coming from, Tantek ?
Aug 18 15:23:31 <DanC> " The grammar element time-second may have the value "60" at the end of
Aug 18 15:23:31 <DanC> months in which a leap second occurs" The XML Schema WG is in the 27th level of
leap-second-hell for the past few months, I gather.
Aug 18 15:24:21 <DanC> yeah... here's the scary bit: " Leap seconds cannot be predicted far into the
future. The
Aug 18 15:24:21 <DanC> International Earth Rotation Service publishes bulletins [IERS] that
Aug 18 15:24:21 <DanC> announce leap seconds with a few weeks' warning."
Aug 18 15:26:03 <Tantek> DanC, which microformats? any/all that use datetime fields.
Aug 18 15:26:36 <DanC> hard to give useful advice, then.
Aug 18 15:26:58 <DanC> I expect they'll use datetime fields for different things that have different
cost/benefit trade-offs
Aug 18 15:27:26 <DanC> do you know of any particular differences that matter to anybody?
Aug 18 15:56:43 <KragenSitaker> RFC3339 suggests -07:00, which seems like an improvement over -0700 anyway
Aug 18 15:56:49 <Tantek> Kragen, agreed
Aug 18 15:57:01 <Tantek> RFC3339 is certainly preferable to the ISO8601 subset in iCalendar
Aug 18 16:05:57 <DanC> Tantek's right, Kragen; iCalendar looks like it solves the local timezone
problem but doesn't.
Aug 18 16:06:14 <DanC> and it's true that there's no standard solution to the local timezone problem
Aug 18 16:06:39 <Tantek> so instead of appearing to solve the problem but not solving it, we chose to
provide the ability to *approximate* the local timezone using e.g. "-07:00"
Aug 18 16:06:49 <DanC> the simplest thing is to have people use Z time in hCalendar. But I gather
that's unacceptably unusable?
Aug 18 16:07:35 <Tantek> DanC, yes, the simplest thing is to have everyone use UTC Z
Aug 18 16:07:38 <Tantek> However
Aug 18 16:07:50 <Tantek> it is not *nearly* as usuable/verifiable
Aug 18 16:07:55 <Tantek> as -07:00 etc.
Aug 18 16:08:02 <Tantek> hence the decision to go with the latter
Aug 18 16:08:12 <Tantek> some degree of human verifiability is important here
Aug 18 16:14:21 <Tantek> DanC, my perception is that RFC3339 is a subset
Aug 18 16:17:00 <DanC> time-numoffset = ("+" / "-") time-hour ":" time-minute
Aug 18 16:17:34 <DanC> ok, then I can't see any differences. (modulo recent leap seconds issues that
may affect xsd:dateTime )
Aug 18 16:18:07 <Tantek> would be interesting to know why Atom 1.0 chose RFC3339 over xsd:dateTime
Aug 18 16:18:21 <Tantek> if there was a "real" reason or if it was arbitrary / coin-flip.
</pre>

Here's an exhaustive [http://www.imc.org/atom-syntax/mail-archive/msg13103.html comparison] from ndw. I think xsd:dateTime also allows unqualified local times, while RFC3339 allows only UTC with no known timezone (-00:00). In the end, Atompub followed the advice of [http://www.imc.org/atom-syntax/mail-archive/msg13244.html Sam Ruby] and [http://www.imc.org/atom-syntax/mail-archive/msg13248.html Scott Hollenbeck], our area director. Atom dates make some additional restrictions on RFC3339, such as uppercase T and Z characters for compatibility with xsd:dateTime, RFC3339, W3C-DTF, and ISO8601. --[http://franklinmint.fm Robert Sayre]

<pre>
Aug 18 16:18:43 <KragenSitaker> rfc3339 is pretty short.
Aug 18 16:19:36 <Tantek> DanC, BTW, which came first? REC for xsd:dateTime or RFC3339?
Aug 18 16:19:50 <DanC> RFC3339 is dated July 2002 ...
Aug 18 16:19:54 <KragenSitaker> Right --- and you might be able to understand xsd:dateTime without
reading all of xml schema, you wouldn't be confident of it
Aug 18 16:20:25 <DanC> W3C Recommendation 28 October 2004 ... but that's 2nd ed...
Aug 18 16:20:47 <DanC> W3C Recommendation 02 May 2001
Aug 18 16:22:10 <DanC> I don't see a BNF in http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#dateTime ...
Aug 18 16:22:43 <KragenSitaker> yeah, appendix D of the current xml schema datatypes document seems
a little scanty, actually
Aug 18 16:23:28 <DanC> ah... 2nd ed of http://www.w3.org/TR/xmlschema-2/#date is much more
explicit about syntax.
Aug 18 16:23:30 <KragenSitaker> it's 1100 words but still doesn't give any examples
Aug 18 16:23:35 <DanC> still, it's given in prose and not BNF
Aug 18 16:24:17 <KragenSitaker> sections 3.2.9 through 3.2.14 seem to be the relevant ones around #date
Aug 18 16:24:29 <KragenSitaker> which is another 2200 words
Aug 18 16:24:42 <DanC> wow... they changed the canonical form of date from always-Z to
timezone-allowed between 1st edition and 2nd edition
Aug 18 16:25:01 <Tantek> Kragen, DanC, these are very good analyses
Aug 18 16:25:21 <Tantek> could I ask you to summarize the pros/cons for each in a new section at
end of http://microformats.org/wiki/datetime-design-pattern
Aug 18 16:25:22 <Tantek> ?
Aug 18 16:25:58 <KragenSitaker> rfc 3339 is 4000 words, excluding the last two pages of boilerplate.
Aug 18 16:26:31 <KragenSitaker> so it's actually longer than the datetime-relevant parts of XSD but it
seems much more rigorous and clear
Aug 18 16:28:37 <DanC> my advice is: normatively cite both, and claim they specify the same
syntax, and let anybody who discovers otherwise send you a bug report
with a test case
Aug 18 16:29:12 <KragenSitaker> danc: nice hack
</pre>

The RFC3339 has a mandatory TIME portion of the DATE-TIME. Some vCard/iCalendar DATE-TIME stamps can omit the TIME. For instance, DTSTART, if that is a full day event, then you can omit the time. BDAY in vCard can be respresented by only a DATE. I like the idea of restricting the possible date formats, but i think that TIME should be optional, which it isn't in RFC3339. - [http://suda.co.uk/ brian suda]

RFC 3339 allows lowercase 't' and 'z' while XSD doesn't. Specifying RFC 3339 plus 'T' and 'Z' MUST be caps will make them the same. - [http://bitworking.org Joe Gregorio]

---

A few questions: asked by [[User:CharlesBelov|CharlesBelov]] 16:57, 24 Apr 2007 (PDT), answered by [[User:JamesCraig|JamesCraig]] on 15:58, 5 Jul 2007 (PDT).

# Would it make more sense for documenting the alternative codings pitting the abbr tag vs. other tags to be on this page? ''Answer: That documentation should go on the [[assistive-technology-abbr-results]] page.''
# Would using the title attribute of the abbr tag to encode the machine-readable date in fact cause a failure of WCAG 2.0 Accessibility? What about USA Section 508? It does appear to violate Technique for WCAG 2.0 [http://www.w3.org/TR/WCAG20-TECHS/#H28 H28: Providing definitions for abbreviations by using the abbr and acronym elements], although that is a supporting document and does not have the force of a guideline. ''Answer: Yes, it appears that is in violation of WCAG, 508, et al, so alternatives are being discussed on the [[assistive-technology-abbr-results]] page.''
# In order to maintain accessibility, would it make sense to enclose the machine-readable date in a span with a style of "display:none" instead of using the abbr tag? ''Answer: please refer to and add any suggestions to [[assistive-technology-abbr-results]].''
# For that matter, wouldn't you want to style such an abbr tag with text-decoration:none to hide that an abbr tag was used? Otherwise, visitors might cursor over the time, see the machine time, and be annoyed that their time was wasted or else be confused. And I don't think you can suppress the title from coming up if the human-readable time was inadvertently hovered. ''Answer: Microformats should not rely on CSS in order to work properly, but again, that discussion can be found here: [[assistive-technology-abbr-results]].''

== Code ==
The following regular expression (parsed VERBOSE) should break apart a datetime and cover many lightly broken cases seen in the wild. This has been tested under Python.

<pre><nowiki>
^
(?P<year>\d\d\d\d)
([-])?(?P<month>\d\d)
([-])?(?P<day>\d\d)
(
(T|\s+)
(?P<hour>\d\d)
(
([:])?(?P<minute>\d\d)
(
([:])?(?P<second>\d\d)
(
([.])?(?P<fraction>\d+)
)?
)?
)?
)?
(
(?P<tzzulu>Z)
|
(?P<tzoffset>[-+])
(?P<tzhour>\d\d)
([:])?(?P<tzminute>\d\d)
)?
$
</nowiki></pre>

== Other Proposals ==

=== strtime instructions as class names ===

Proposal by DavidLaban (alsuren on freenode) on 8 Jun 2008
It might be possible to have a slightly more readable/extensible/elegant format:
<pre><nowiki>
<span class="strtime format:_%d_%B_%Y_" > 16 March 1987 </span>
</nowiki></pre>
Notes:
# Underscores are used to replace whitespace, because otherwise the the formatting string will be split into an unordered set of class attributes by many parsers (thanks go to bogdanlazarsb and gsnedders on irc for explaining this to me).
# Some subset of the placeholders should be chosen from those which are supported by both python http://docs.python.org/lib/module-time.html and php http://uk3.php.net/manual/en/function.strftime.php
# A name for the class should be decided upon. strtime might not be the best name.
# Measures should be taken to avoid the format string accidentally conflicting with other valid classes (In the above example, I have prefixed it with the string "format:")
# It might be sensible (when parsing) to strip excess whitespace from the format string and contents. This is not done in this example.
# Example python code follows.

<pre><nowiki>
date = (1987,03,16,0,0,0,0,0,0)
format = " %d %B %Y "
# To encode:
classes = ["strtime"]
encoded_format = "format:" + format.replace(' ', '_')
classes.append(encoded_format)
content = time.strftime(format, birthday)
# ... dump classes and content into your document however you want

# To decode (assuming that you have managed to extract class and format from the document already):
if "strtime" in classes:
possible_formats = [ item for item in classes if item.startswith('format:') ]
assert len(possible_formats) == 1
format = possible_formats[0].strip('format:').replace('_', ' ')
date = time.strptime(content, format)
</nowiki></pre>

==== problems with strtime proposal ====

# Possible abuse of the class attribute. microformats limit the use of the class attribute to marking up additional semantics about the data, not for (potentially) arbitrary processing/programming instructions
#* HTML 4.01 Recommendation [http://www.w3.org/TR/REC-html40/struct/global.html#adef-class defines] the <code>class</code> attribute as being "for general purpose processing by user agents". [[User:TobyInk|TobyInk]] 13:21, 8 Jun 2008 (PDT)
# Requires authors to think like programmers. The larger problem is that the proposal asks web authors to think like programmers, which severely limits the number of web authors which will be able to use the technique, since the vast majority of web authors are ''not'' programmers and have never heard of "strtime", whereas most authors (even people) on the web have seen dates like 2005-06-20 and easily understand what they mean.

In general, any publishing method that requires the author to think like a programmer is a non-starter. It is a much more of a barrier than simply using ISO8601/RFC3339, and that barrier is a far worse tradeoff than the duplication / DRY violation compromise.
[[User:Tantek|Tantek]] 09:52, 8 Jun 2008 (PDT)

* Another problem: if %A/%a/%B/%b are allowed, this raises potential problems with internationalisation. Will parsers be required to understand the names and abbreviations for days and months in potentially hundreds of different languages? [[User:TobyInk|TobyInk]] 14:09, 8 Jun 2008 (PDT)

=== Machine-data in class===
The BBC ([http://microformats.org/discuss/mail/microformats-dev/2008-June/000552.html uf-dev archive, 20/06/08, "Using class for non-human data"]) has proposed as an alternative to the empty span and title solution to use the class name in the following way:
<pre><nowiki>
<span class="dtstart data-20051010T10:10:10-0100">10 o'clock on the 10th</span>
</nowiki></pre>
Pros:
* Allows data to be represented in a "non-harmful" way. Will not be read aloud by screenreaders or seen as tooltips.
* Minimises mark-up used.
* Arguably more semantic than use of "title" attribute for non-human data.

Cons:
* data in the class attribute has already been discussed numerous times in the mailing list over the years and rejected and documented as an [[anti-pattern]] - captured [http://microformats.org/wiki?title=anti-patterns&diff=24271&oldid=24270 on the wiki this past January 2008].
* Possible misuse of class attribute, although as noted previously, the HTML spec states "for general purpose processing by user agents".
* The class attribute has been adopted by the broader web design community to "subclass" element semantics, and to layer additional semantics. To date, microformats has followed this existing practice developed by modern web designers ("paving the cow-paths"). This use of class for data is outside all current practices.

Discussion:
* This proposal smells icky, but I can't quite put my finger on why. Considered objectively, it does seem to be the least harmful solution proposed so far. [[User:TobyInk|TobyInk]] 06:06, 21 Jun 2008 (PDT)
* I really like it, especially given the HTML4 spec gives this as an IMO perfectly valid use (on both id and class, with the following examples given in the id section: "identifying fields when extracting data from HTML pages into a database, translating HTML documents into other formats, etc."). Clean and simple. [[User:Dracos|Dracos]] 03:53, 23 Jun 2008 (PDT)
* I suggest dropping the redundant 'data-' prefix, unless someone can suggest a feasible case with two time-stamps requiring different prefixes. The proposal then becomes [http://www.robertnyman.com/2008/04/28/do-we-really-need-microformats/#comment-263408 one I've made before] [[User:AshSearle|AshSearle]]
** Valid class names cannot begin with a number, so a date needs some sort of letter prefix. It's sensible to make this prefix meaningful and reusable in some way. [[User:Phae|Phae]]
*** They can't in CSS, but they can in (X)HTML. http://examples.tobyinkster.co.uk/numeric-classes.html [[User:TobyInk|TobyInk]] 06:53, 24 Jun 2008 (PDT)
**** Creating classes in HTML that can't be referenced in CSS is a bad thing. Using colons and starting with numbers fall into that category. http://www.w3.org/TR/CSS21/syndata.html#characters Also, replacing whitespace with underscores breaks the ISO compatibility, which sorta defeats the whole point of using existing standards. Finally the class names are unordered, so trying to use them in a series is a bad idea. --[[User:Atamido|Atamido]] 11:43, 30 Jul 2008 (PDT)
** Not to advocate too strongly for designing for parsers (generally a bad idea), *but* having a 'data-' prefix on a class name would make identifying data orders of magnitude easier for parsing. Otherwise, how do we know what's data and what's just another class name for some other purpose? [[User:DrewMcLellan|Drew]]
** A 'data-' prefix would help authors tasked with maintaining or reviewing a page to understand the purpose of a class name that may have been applied by another author. The data prefix communicates very simply that the class name is precisely that, data. Therefore the value is less likely to be accidentally removed or changed, making for a more robust design. [[User:DrewMcLellan|Drew]]
*** I concede - regardless of whether it's valid (X)HTML / CSS - a prefix is needed to distinguish data values from genuine content. ISO 8601 allows date-time to be as simple as "2004", which could easily be misinterpreted. e.g. if a CMS outputs product model numbers into the class attribute for some other purpose. --[[User:AshSearle|AshSearle]] 01:42, 25 Jun 2008 (PDT)
*** Using <code>data-</code> as the prefix here is undesirable, as it now conflicts with HTML5's proposed <code>-data</code> prefix on attributes. It's undesirable to set ourselves up for future confusion with our own conflicting specification of ‘a data prefix’. A different prefix should be considered. See: [http://www.w3.org/html/wg/html5/#custom HTML5 Editors Draft: Embedding Custom Non-Visible Data] —[[User:BenWard|BenWard]] 07:34, 16 Jul 2008 (PDT)
* -1 [[User:Tantek|Tantek]]. I'm vehemently opposed to putting data in the class attribute. We ''must'' find better alternatives. We must not go down the path of invisible (dark) (meta)data - IMHO that [[principle]] is inviolable for microformats.
** [[User:JakeArchibald|JakeArchibald]] If you're so opposed, it'd be useful to see some justification.
*** See above cons. Already discussed/rejected many times in the history of microformats discussions. In short, quit wasting time on old ground. Abuses class attribute, or if you prefer, introduces a *new* use of the class attribute, unlike microformats to-date which have simply made use of a well established semantic of the class attribute. And worst of all, completely violates the visible data [[principle]]. Rejectable on that alone.
**** The fact that something has been discussed and rejected before is not sufficient grounds for dismissing it out of hand once additional research and thinking has taken place. The <abbr> datetime pattern arguably abused the title attribute and introduced a new use of the title attribute. In the example given (<code><nowiki><span class="dtstart data-20051010T10:10:10-0100">10 o'clock on the 10th</span></nowiki></code>), the data is presented as "10 o'clock on the 10th" - very visible. Yes, of course, it's possible to abuse this proposed pattern, and hide the data, but the same can be said of the abbr pattern or even the class pattern given CSS's display:none property. Experience shows that in most cases, people ''won't'' abuse the pattern to hide data, as they actually ''want'' to show the data on their pages. [[User:TobyInk|TobyInk]] 13:52, 24 Jun 2008 (PDT)
**** It's not an abuse of the class attribute according to the HTML spec. as I read it. Whereas using title for non-human data is (the spec says audio agents may read it aloud, for example). If it's a new use, it's one the writers of HTML4 considered, so it wasn't new to them. [[User:Dracos|Dracos]] 03:38, 25 Jun 2008 (PDT)
** Relevant princeples are 'humans first, machines second', and 'visible data is ''better'''. These are ''preferences'', not inviolable principles. Besides, the existing datetime spec doesn't adhere to these principles anyway: prioritising humans first, <code><nowiki>let's discuss this at the next meeting</nowiki></code> should be marked up as <code><nowiki>let's discuss this at the <abbr title="28th June 2008 at 3:15pm">next meeting</nowiki></code>. There's a conflict between human- and machine-readable dates. It makes more sense to 'hide' the machine-readable data in the only attribute available to us: <code>class</code>. --[[User:AshSearle|AshSearle]] 03:02, 25 Jun 2008 (PDT)
*** Indeed - by their nature, ''principles'' are ''generalisations'', and while broadly useful, usually have exceptions. After experience, the microformats community is beginning to see some of these. Human vs machine dates is the one gathering the most interest at the moment, largely thanks to <abbr class="help" style="border-bottom:1px dotted" title="the Web Standards Project">WaSP</abbr> and <span class="help" style="border-bottom:1px dotted" title="the BBC">auntie</span>, but I think other properties which will probably emerge as exceptions to the general microformats principles are hReview's <code>type</code> property, and the its namesake subproperty for hCard's <code>tel</code>, <code>email</code> and <code>adr</code> (and <code>label</code>?) properties. [[User:TobyInk|TobyInk]] 12:51, 25 Jun 2008 (PDT)

==== Experimental Parser Support ====

[http://buzzword.org.uk/cognition/ Cognition 0.1 alpha 10] will include experimental support for this pattern, and the [http://srv.buzzword.org.uk Cognition web service] already does. Notes:
* Support is ''opt-in''. Publishers must explicitly request support for the pattern, by including a [[profile-uris|profile URI]] of <code><nowiki>http://purl.org/uF/pattern-data-class/1</nowiki></code> in their document head.
* Support is not limited to date-time properties, but any microformat properties.
* data-X classes must use percent-encoding to encode spaces and other characters not allowed in class names.
* The data-X class must be found on the same element as the microformat property class. That is, you cannot use: <pre><nowiki><span class="dtstart"><span class="data-20051010T10:10:10-0100">10 o'clock</span></span></nowiki></pre>
<ul><li>Multiple data-X classes may occur on the same element. When these are found, the longest string is used. This allows for: <pre><nowiki><span class="dtstart data-2005 data-200510 data-20051010">The 10th</span></nowiki></pre> which may be useful for styling or other non-microformat purposes.</li>
<li>Can be combined with value excerpting. e.g. <pre><nowiki>
<p class="dtstart">
The concert will be held on
<span class="value data-20080804">the 4th of August</span>
starting at
<span class="value data-T193000">7:30pm precisely</span>.
</p>
</nowiki></pre></li></ul>

=== date and time separation using value excerption ===

==== summary ====
By specifying a more precise parsing of the use of "value" excerption inside all datetime properties (e.g. dtstart, dtend, published, updated etc.), dates and times can be marked up separately, thus reducing/minimizing (and potentially eliminating) the readability issues that come with compound ISO8601 datetimes.

==== introductory example ====
The sentence:

<pre><nowiki>
The weekly dinner is tonight at 6:30pm.
</nowiki></pre>

would be marked up as:

<pre><nowiki>
The weekly dinner is <span class="dtstart"><abbr class="value" title="2008-06-24">tonight</abbr>
at <abbr class="value" title="18:30">6:30pm</abbr></span>.
</nowiki></pre>

==== advantages ====
* re-uses the readable [[abbr-date-pattern]]
* identifies a similarly readable abbr-time-pattern.
* minimizes DRY violation distance, keeps machine data on exactly the same element as the respective human data
** even better than [[abbr-datetime-pattern]] does, which, in practice from experience often required specifying the date in machine readable form on the human readable time (separate from the human readable date).
* introduces no new class names - [[principle]] of minimal invention
* introduces no new use of the class attribute - principle of minimal invention again
* introduces no new syntax ([[datetime-design-pattern#problems_with_strtime_proposal|see above]] about any publishing method that requires the author to think like a programmer being a non-starter, and introducing new syntax almost always requires authors to think like programmers).
* and most importantly, introduces no dark data.

==== issues ====
Some potential issues were raised in IRC, and it helps to document/resolve them so that they are not brought up repeatedly.
* [[http://rbach.priv.at/Microformats/IRC/2008-06-24#T163114 Does this sufficiently address the concerns raised with the current use of abbr-pattern?]]
*# The [[abbr-date-pattern]], as documented and explained by [[User:Adactio|Jeremy Keith]] is just fine (in contrast to the [[abbr-datetime-pattern]]).
*# Similar to the [[abbr-date-pattern]], this proposal implies/introduces the abbr-time-pattern, which is similarly acceptable.
** That's not a complete coverage of the ABBR complaints. Separating into 2008-06-07 and 18:03 improves the ability for humans to consume the data, but still exposes data through tooltips and speech in formats that the publisher did not choose to use. --[[User:BenWard|BenWard]] 04:52, 25 Jun 2008 (PDT)
*** if a site publisher wishes to customize the presentation of tooltips, they can do so with a nested span with title.
**** That proposes extraneous mark-up maintain the publisher's wish not to have a tool-tip in the first place. I object to a microformat pattern requiring an immediate work-around to meet publisher's desires. It goes against ‘Humans first…’. --[[User:BenWard|BenWard]] 09:09, 30 Jun 2008 (PDT)
** Additionally, it does not solve the semantic misuses of ABBR. That ‘tonight’ is ever a textual, human abbreviation of ‘2008-06-24’ is not accepted, nor is it possible to use this mark-up and always maintain proper sentences with the expanded form. e.g. <code>it's my <abbr class="bday" title="2005-06-20">birthday today</abbr>!</code> becomes ‘it's my 2005-06-20!’. That content remains broken by the continued stretch of ABBR semantics. --[[User:BenWard|BenWard]] 04:52, 25 Jun 2008 (PDT)
*** I concur. We need to explore a solution that allows authors to choose what mark-up they use to best fit their implementation. Publishing practices and desires show us that authors are not willing to compromise the semantics of abbr. [[User:Phae|Phae]] 04:30, 27 Jun 2008 (PDT)
* [[http://rbach.priv.at/Microformats/IRC/2008-06-24#T163435 That's getting pretty complicated]]
** Much less complicated than inventing yet another syntax ( " { ... } " ???? ) that web authors would have to learn.
*** But it's all in one place, rather than spreading it out.
**** The spreading it out is what current content publishing practices do already! It is much more important to map the machine data as close to the existing publishing practice as possible, than to try to "put it all in one place". The "put it all in one place" way of thinking is why people ended up sticking so much invisible metadata in the head of the document, which we know fails.
* Audio rendition of such titles can be nonsensical - "The weekly dinner is two thousand and eight dash zero six dash twenty four at eighteen thirty."

==== content requirements ====
Some requirements which enhance both human readability, ''and'' machine parsability (best of both) :
* date value excerpts MUST use hyphen separators. E.g. 2008-06-24. Not ok:20080624.
* time value excerpts MUST use colon separators (seconds optional, implied :00 if absent). E.g. 18:30 or 18:30:00. Not ok:183000.
* timezone value excerpts MUST use leading plus or minus and NO colon separator. E.g. -0700. Not ok:-07:00.

==== derivation ====
It's important to document the derivation/background of a brainstorm/proposal as it allows others to see some of the thinking that went into it, and avoid having to rediscuss alternatives already considered, and helps provide understanding as to why aspects of the design are as they are.
===== example with datetime =====
Here is a short code example:
<pre><nowiki>
the weekly dinner is tonight at <span class="dtstart">2008-06-24T18:30</span>
</nowiki></pre>
===== example with abbr datetime =====
However that's not the easiest to read, nor do most people publish that as human visible text, so per the abbr-datetime pattern:
<pre><nowiki>
the weekly dinner is tonight at <abbr class="dtstart" title="2008-06-24T18:30">6:30pm</abbr>
</nowiki></pre>

which has raised two issues:
# When "2008-06-24T18:30" is inspected by a human reading a tooltip, or spoken by a screen reader, it's not the most understandable thing (precise citation needed, perhaps an mp3 with screen reader used version info).
# There is a non-local violation of DRY (which IMHO is a worse problem, as it leads to worse data quality -[[User:Tantek|Tantek]]). That is, the "date" information is now not only in the text twice (as it was before), but those two instances of the date information are not on the same element, which makes it worse. That is, "tonight" is in the prose, ''outside'' of the element with the precise date "2008-06-24".

In analysis of examples of event information on the web, the date and time are often published in separate elements, often for display purposes.

Thus it is this existing content publishing practice which leads to this brainstorm proposal, to essentially to introduce a date and time value excerption longhand.

(Initially [http://rbach.priv.at/Microformats/IRC/2008-06-21#T181634 Tantek's idea that he bounced off Jeremy Keith] ([http://rbach.priv.at/Microformats/IRC/2008-06-24#T124652 similar idea conceived by Drew independently]) was to [http://rbach.priv.at/Microformats/IRC/2008-06-24#T161819 introduce new classes "datevalue", "timevalue"] and "tzvalue" for this purpose, but [http://rbach.priv.at/Microformats/IRC/2008-06-24#T171603 Bob Jonkman pointed out] that HTML5's time parsing algorithm enables a single <nowiki><time></nowiki> element to contain dates or times (with or without timezone) without having to explicitly say whether the value contains dates or times (with or without timezone). [http://rbach.priv.at/Microformats/IRC/2008-06-24#T171723 Bob then proposed] that thus all was needed was a single new "datetime" class name. This was the key realization that allowed minimal invention. Tantek pointed out that since from the type of property we already know it is a datetime, [http://rbach.priv.at/Microformats/IRC/2008-06-24#T171835 there was no need for even one new class name], that we could simply re-use "value" excerption, and simply more precisely specify the semantics/parsing in the case of datetime properties.)

===== example with new date and time value excerpts =====
Thus we markup the date and time separately, as value excerpts, using the [[abbr-date-pattern]] and an implied parallel abbr-time-pattern:

<pre><nowiki>
The weekly dinner is <span class="dtstart"><abbr class="value" title="2008-06-24">tonight</abbr>
at <abbr class="value" title="18:30">6:30pm</abbr></span>.
</nowiki></pre>

===== separate subtrees =====
The proposal also allows setting the date and time in separate element subtrees as well, which may be necessary for some document structures:

<pre><nowiki>
the weekly dinner is <span class="dtstart"><abbr class="value" title="2008-06-24">tonight</abbr></span>
at <span class="dtstart"><abbr class="value" title="18:30">6:30pm</abbr></span>.
</nowiki></pre>

Note the two instances of dtstart, one of which sets the date for the dtstart, and the other of which sets the time.

The idea being, when a parser sees a datetime property (e.g. dtstart) with a value excerpt, that it only "set" the component of its full value that is specified by the value excerpt (e.g. the date), and that if lacking a complete datetime, it continue to parse additional instances of that datetime property for the remaining component(s) (e.g. the time).

Of course this only works for singular properties, but fortunately all instances of datetime properties so far are singular, so this works.
* hCard's <code>rev</code> is plural. [[User:TobyInk|TobyInk]]
** can someone give a reference to this being the case? The RFC says "The value distinguishes the current revision of the information in this vCard for other renditions of the information." Does it make sense to have multiple REV dates in a single vCard?
*** The RFC is ambiguous as usual, but a contact card could conceivably have had several changes made to it, with a <code>rev</code> for each. ("Change logs" are fairly common on the web.) The [[hcard|hCard spec]] is fairly specific about which properties are [[hcard#Singular_vs._Plural_Properties|singular]] and which are not, and <code>rev</code> is not included in the list of singular properties.

===== reusing date data for multiple datetime properties =====
This also provides a *very* convenient way to re-use the same date information for start and end, e.g. expanding the example:

<pre><nowiki>
the weekly dinner is <span class="dtstart dtend"><abbr class="value" title="2008-06-24">tonight</abbr></span>
from <span class="dtstart"><abbr class="value" title="18:30">6:30</abbr></span> -
<span class="dtend"><abbr class="value" title="20:30">8:30pm</abbr></span>.
</nowiki></pre>

Note what just happened. we just eliminated another duplication of date information by reusing the start *date* information for the end *date* information and *only* specifying the end *time* information separately for the two properties.

Reducing the duplication (or triplication) of such data helps to reduce the chances of (even inadvertent) data corruption/drift/divergence among any duplicates.

===== time zones =====
There are a few choices for timezones.
# Simply include the time zone information as part of the time "value". <br /> E.g. <code><nowiki><abbr class="value" title="18:30-0700">6:30pm</abbr></nowiki></code>
# Or use another value excerpt for the timezone (was: <del>introduce the class name "tzvalue"</del>) <br /> E.g. <code><nowiki><abbr class="value" title="18:30">6:30pm</abbr> <abbr class="value" title="-0700">PDT</abbr></nowiki></code>
# Or allow both and let web authors decide. This is the current leaning.
#* if web authors want to specify timezone as part of the time (first example above), they can,
#* or if web authors visibly publish the timezone separately (second example above), then they can mark that up.
#* or if web authors wish to omit timezone information, they can do so as well, as most do today. In practice this works fine, as it creates a "floating" time which works fine in far more than the 80/20.

(more to come, documenting [http://rbach.priv.at/Microformats/IRC/2008-06-24#T161740 from IRC logs])

==== discussion ====
Opening up a discussion section even though documentation [http://rbach.priv.at/Microformats/IRC/2008-06-24#T161740 from IRC logs] is still in progress. :)

* regarding the [[datetime-design-pattern#advantages|advantage]] of "and most importantly, introduces no dark data."
** "Dark data" is sometimes what publishers *want* to publish. To use the example of TV schedules which kick started the renewed discussion in this area, publishers will often not want to display the date. For instance, if a page entitled "Tomorrow's TV" and containing 300 different programmes marked up with <code>dtstart</code>, it is superfluous to explicitly display the date for each one. With this proposed solution the [[include|include pattern]] could be used to include the date into each vevent, but a visible link to the date on each programme would simply be confusing. Sometimes it just makes sense to hide some of the information you're publishing as a microformat - because the information you want to make explicit to parsers can be inferred from context by humans, or is more appropriately displayed at a different level of granularity for machines and humans. [[User:TobyInk|TobyInk]] 14:26, 24 Jun 2008 (PDT)
*** It doesn't matter whether publishers *want* to publish dark data or not. Invisible data always leads to poorer quality data. Publishers publish all kinds of invisible metadata in the heads of documents etc. because they want to, but their desire doesn't stop the data from becoming obsolete, diverging from the actual visible data etc. The quality of the data matters more than any publishers wish(es) of publishing in a specific format, or in a hidden way. In the example you gave, using the include pattern in that way would not result in any visible links, but merely empty include anchors. It never makes any sense to actually hide "some of the information you're publishing as a microformat", because historically that always results in some loss of data quality over time and thus the microformats [[principle]] of visible data instead of invisible metadata. [[User:Tantek|Tantek]] 14:32, 24 Jun 2008 (PDT)
**** All microformats hide ''some'' data. In the example <code><nowiki><span class="tel">01632 960123</span></nowiki></code>, the information that the long string of numbers represents a telephone number is invisible. And making it visible (<code><nowiki>Tel: <span class="tel">01632 960123</span></nowiki></code>) violates DRY. It's just a matter of where to draw the line.
***** That statement makes the mistake of conflating *type* data and *content* data. "tel" is not content data, just as <nowiki><p></nowiki> is not content data. It's markup, indicating the type of the data. Markup (type data) being invisible to the user has worked just fine. Content (content data) being invisible to the user is the problem of dark data. Or rather, if you think that everything is data, then you really should be spending time developing in a system that is built on that assumption, e.g. RDF, rather than microformats, which are built on HTML, and the clear separation of type of data (HTML elements, microformats properties) and content data (inner text, text attribute values).
****** My point is that there isn't a ''distinction'' between the two, but a ''continuum''. The choice of where to draw the line is never a clear one and always somewhat arbitrary. The vCard standard could quite easily have ended up with separate "TEL", "FAX" and "CELL" properties, in which case hCard would have ended up with <code><nowiki><foo class="tel"></nowiki></code>, <code><nowiki><bar class="fax"></nowiki></code> and <code><nowiki><baz class="cell"></nowiki></code>. Going the other way, they could have stored e-mail addresses as mailto: URLs, and then hCard would have <code><nowiki><a class="url" href="mailto:quux@example.com"></nowiki></code>. They chose the way they did, and as a result in hCard the distinction between a mailto: URI and an http: URI is largely invisible (in most circumstances only obvious by looking at the status bar when hovering), but the distinction between a telephone number and a fax number is visible. But that wasn't the only possible (nor the only reasonable) outcome.

=== HTML 5 <code><time></code> Element ===

[http://microformats.org/wiki/hcalendar-issues#html5-time-element See hCalendar issues]

=== Plain Old English alternative to ISO date ===

Example (in English):

<pre>
<abbr title="January 25th, 2008" class="dstart" lang="en-us">1/25</abbr>
</pre>

<pre>
<span class="dstart">January 25th, 2008</span>
</pre>

If <code>lang="en-us"</code>, the format of the date used in the <code>title</code> attribute must conform to [http://www.ego4u.com/en/cram-up/vocabulary/date/written dates writing rules in American English].

Example (in French):

<pre>
<abbr title="25 Janvier 2008" class="dstart" lang="fr">25/1</abbr>
</pre>

If <code>lang="fr"</code>, the format of the date used in the <code>title</code> attribute must conform to date writing rules in French.

====Benefits====

* Human-hearable: should work nicely with screen readers (to be tested).
* Human-readable
* Compliance with semantics of abbr.
* Very easy to use by HTML human authors.
* DRY compliant if HTML human authors are willing to write in correct English

====Discussion====

* Locale-specific parsing logic.
* Not all cultures use the same calendar — Dan Brickley
* There are situations where markup clues used for localisation might be misleading, such as people using microformats in a post on a site they do not themselves run that may even be in a different country. (a shared blogging site that allows html tags in posts would be a good example here) — Michael MD
** Couldn't the person or tool adding the microformat annotation also add a lang attribute at the same time? — Benjamin Hawkes-Lewis
* Cognition already supports this as a last ditch attempt at parsing dates - but I wouldn't recommend it get adopted widely. It's too unreliable; too much work to deal with internationalisation; too much work full-stop in languages that don't provide a handy library that takes care of most of the work. — [[User:TobyInk]]
** I don't think we need to support all locales at once. I don't know in how many written languages BBC publishes in, but it might be that supporting en-uk and en-us might be enough for a start. Also, one can imagine that Microformats tools could focus on the most common written languages and then expose hooks for others to implement support for other locales. — Guillaume Lebleu
** What are our priorities? Making programmers' life easier or making content authors and content readers' life easier? — Guillaume Lebleu
*** In Australia dd/mm/yyyy is commonly used, but a significant minority of sites in Australia use US-style mm/dd/yyyy because it is the default setting in their CMS. How would a parser be able to tell which part is the day and which is the month? Getting it wrong would be worse than not getting it at all! Until the use of ambiguous formats can be ''wiped out'' we ''will'' need a version for machines! — Michael MD
*** problem which hasn't been raised with regards to this proposal is that even though you are proposing a fixed date format, because it *looks* like natural language, authors will assume that it *is* natural language, and simply start including dates in whatever format they like. Then you get an NLP "arms race" between publishers and parsers. If you don't believe that that will happen, take a look at what happened with RFC 822 dates, which are simply a mess. — [[User:TobyInk]]
**** Very true the more you make the date look like natural language, the less it looks like a fixed format. I really don't want us to get involved in any form of NLP, it just would not work. I think it was Mike who said that dates have to be parsed correctly, no level of error is acceptable. I don't want to travel to an event on the wrong day because a parser got the date wrong — Glenn Jones

====Notes====

* Could work alongside with the existing [[datetime-design-pattern]]: if ISO date parsing fails, try parsing the title as a human-readable plain old English/French/... date according to the locale.

===<code><object></code> element to represent dates===

* Re-raised by George Brocklehurst on June 25th 2008.

The idea was to do something like this:

<pre><code><object data="20050125">January 25</object></code></pre>

* From what Tantek [http://tantek.com/log/2005/01.html said on his blog] , the main reason for not using objects was that they were not well supported in Safari. However, Safari's object support is now much improved: fallbacks are supported and display:inline and intrinsic sizing will work correctly. Safari 2.0.2, which came out in November 2005, was the first version to [http://webkit.org/blog/32/webkit-fixes-in-safari-202-mac-os-x-1043/ contain these improvements]. — George Brocklehurst
* The following appears to be well behaved inline in Safari 2.04 and 3.1.1, Firefox 1, 1.5, 2 and 3, and Opera 7, 8 and 9: <code><object class="dtstart" data="data://20080712"></object></code>. Test case: http://pastie.org/224023 — Ben Ward
** IE 6, 7 and the beta version of IE 8 all visibly render the object element as a small box, similar to the way they would render a missing image: http://georgebrock.com/misc/object-in-ie.png — George Brocklehurst
** Absolute URIs can't start with a number, but relative ones can - and the data attribute is permitted to contain relative URIs. [Don't need to use data:// URI) — Toby A Inkster
* Could also look at <code><object class="dtstart"><param name="value" value="20050125" />January 25</object></code> — Scott Reynen
* 1. The purpose of the <object> element is to allow the browser to run an external application for a non-native data type (e.g., Java applet). See: http://www.w3.org/TR/REC-html40/struct/objects.html#h-13.3. Object is not the right way to go in this case. — Sarven Capadisli

== See Also ==

* [[Main_Page#Design_Patterns|All microformat design patterns]]
* [[abbr-design-pattern]] is used by [[datetime-design-pattern]]
* [[date-design-pattern]] is a subset of [[datetime-design-pattern]]
* HTML 4.01 definition of <code><[http://www.w3.org/TR/REC-html40/struct/text.html#edef-ABBR abbr]></code> element
* RFC [http://www.faqs.org/rfcs/rfc3339.html 3339]: Date and Time on the Internet: Timestamps
* W3C: [http://www.w3.org/TR/NOTE-datetime Note on Datetimes]
* Markus Kuhn: [http://www.cl.cam.ac.uk/~mgk25/iso-time.html A summary of the international standard date and time notation]
* Wikipedia: [http://en.wikipedia.org/wiki/ISO_8601 ISO 8601]

irc-people

2008-07-30T18:03:04Z

Atamido: add myself

A list of [[irc|IRC]] regulars, sorted by nick, and their normal timezones (winter/summer).

* {{irc user|Amodal1| amodal1|-0500/-0600}}
* {{irc user|Adam Ballai|AdamBallai|-700/-700}}
* {{irc user|Adam Craven|AdamCraven|+0000}}
* {{irc user|Alexander Graf|AlexanderGraf|+0100}}
* {{irc user|Tomasino|aloneone|-0500}}
* {{irc user|AmanuelTewolde|Amanuel|-0500/-0400}}
* {{irc user|Amette|amette|+1000}}
* {{irc user|Amir Guindehi|AmirGuindehi|+1000}}
* {{irc user|Andr3|andr3|+0000}}
* {{irc user|Ajaswa|Andrew Jaswa|-0500}}
* {{irc user|AndrewDisley|AndrewDisley|+0000}}
* {{irc user|AnselHalliburton|anselxyz|-0800/-0700}}
* {{irc user|Ashe Dryden|Ashe|-600}}
* {{irc user|Ashley|Ashley|+1000}}
* {{irc user|Atamido|Atamido|-0600/-0500}}
* {{irc user|Azathoth|Florian Beer|+1000}}
* {{irc user|Tyler Roehmholdt|Baristo|-0800/-0700}}
* {{irc user|BenjaminCarlyle|BenjaminCarlyle|+1000}}
* {{irc user|HenriBergius|bergie|+0200/+0300}}
* {{irc user|Ben Ward|BenWard|+0000}}
* {{irc user|BenWest|bewest|-0800/-0700}}
* {{irc user|B.K._DeLong|bkdelong|-0500/-0400}}
* {{irc user|Robert|blueace|+0100}}
* {{irc user|BluesMoon|bluesmoon|+0530}}
* {{irc user|BobChao|BobChao|+0800}}
* {{irc user|Bob Jonkman|BobJonkman|-0500/-0400}}
* {{irc user|Boneill|boneill|+0000}}
* {{irc user|Brian|briansuda|+0000}}
* {{irc user|TimT|bringo|-0800/-0700}}
* {{irc user|Briski|Briski|+0000}}
* {{irc user|BryanL|BryanL|-0500/-0400}}
* {{irc user|BryanRieger|Bryan Rieger|+0000}}
* {{irc user|Bug-E|Bug-E|+0200}}
* {{irc user|CarlaHufstedler|carlamagpie|-0500/-0400}}
* {{irc user|Colin_Barrett|cbarrett|-1000}}
* {{irc user|Cognizance|Cognizance|-0800/-0700}}
* {{irc user|ColinDDevroe|cdevroe|-0500/-0600}}
* {{irc user|Cgriego|cgriego|-0600/-0500}}
* {{irc user|Charlvn|Charl|+0200/+0200}}
* {{irc user|CharlesRoper|charles_r|0000/+0100}}
* {{irc user|ChristopherStJohn|cks|-0600/-0500}}
* {{irc user|JeremyBoggs|clioweb|-5000/-4000}}
* {{irc user|Cloud|Cloud|+0000}}
* {{irc user|Cruster|cruster|+0200}}
* {{irc user|Csarven|csarven|-0500/-0400}}
* {{irc user|ChrisBrentano|ctb|-0800/-0700}}
* {{irc user|DanC|DanC|-0600/-0500}}
* {{irc user|DanielBurka|DanielBurka|-0400}}
* {{irc user|DanielJohnLewis|danieljohnlewis|0000}}
* {{irc user|DannyAyers|danja|+0100/+0200}}
* {{irc user|Dave Cardwell|davecardwell|+0000}}
* {{irc user|DavidMead|DavidMead|-0400}}
* {{irc user|DavidRussell|davidrussell|-0600/-0500}}
* {{irc user|DBounds|Darren Bounds|-0500}}
* {{irc user|Ddonat|David Gratton|-0800/-700}}
* {{irc user|DenisDefreyne|ddfreyne|+0100/+0200}}
* {{irc user|DeanEro|deanero|-0800/-0700}}
* {{irc user|DeepText|Deep Text|-0800/-0700}}
* {{irc user|DerrickPallas|DerrickPallas|-0800/-0700}}
* {{irc user|DimitriGlazkov|dglazkov|-0600/-0500}}
* {{irc user|DiegoBudny|DiegoBudny|<small>-unspecified-</small>}}
* {{irc user|DKerzman|DKerzman|-0600}}
* {{irc user|Dan Kubb|dkubb|-0800/-0700}}
* {{irc user|DrErnie|DrErnie|-0800/-0700}}
* {{irc user|DrewMcLellan|drewinthehead|+0000/+0100}}
* {{irc user|DrewBell|droob|-0600/-0500}}
* {{irc user|DimitriosZachariadis|dzach|+0200/+0300}}
* {{irc user|DydimusTK|dydimustk|-0600}}
* {{irc user|Ed Summers|edsu|-0500/-0400}}
* {{irc user|Enric|Enric|-0800/-0700}} (alt sp "enric")
* {{irc user|Evan|evanpro|-0500}}
* {{irc user|Evan|e_s_p|-0500}}
* {{irc user|EdwardWelker|ewelker|-0500}}
* {{irc user|ChrisMessina|factoryjoe|-0800/-0700}}
* {{irc user|Fil|Fil|+0200}}
* {{irc user|CFinke|Finke|-0700/-0600}}
* {{irc user|MarkoMrdjenovic|friedcell|+0100/+0200}}
* {{irc user|GarethR|garethr|+0000/+0100}}
* {{irc user|Grantbow|Grantbow|-0800/-0700}}
* {{irc user|Griffin|Griffin|-0600/-0500}}
* {{irc user|Guillaume Lebleu|glebleu|-0800}}
* {{irc user|Aubergine10|Guy Fraser|+0100/+0000}}
* {{irc user|HenrichPoehls|HenrichP|+0100}}
* {{irc user|IanHickson|Hixie|-0800/-0700}}
* {{irc user|Hlb|hlb|+0800-0700}}
* {{irc user|EdwardOConnor|hober|-0800/-0700}}
* {{irc user|Ichigo|ichigo|+1000}}
* {{irc user|Alper|illustir|+0100}}
* {{irc user|Inkbase|inkbase|-0800/-0700}}
* {{irc user|IwaiMasaharu|iwaim|+0900}}
* {{irc user|Izo|IZO|<small>-unspecified-</small>}}
* {{irc user|JamieKnight|JamieKnight|+1000/0000}}
* {{irc user|JoeGregorio|jcgregorio|<small>-unspecified-</small>}}
* {{irc user|WizardIsHungry|jcw9|-0500/-0400}}
* {{irc user|Adactio|Jeremy Keith|+0000}}
* {{irc user|jrodgers|JesseRodgers|-0500}}
* {{irc user|JasonK|jkridner|-0600/-0500}}
* {{irc user|JeffMcNeill|jeffmcneill|-1000}}
* {{irc user|JimboJW|jimbojw|-0600/-0500}}
* {{irc user|Jonathan_Arkell|jonnay|-0700/0600}}
* {{irc user|JosephHolsten|josephholsten|-0600/-0500}}
* {{irc user|JulianStahnke|julianstahnke|+0000}}
* {{irc user|Kapowaz|kapowaz|+0000/+0100}}
* {{irc user|Keri Henare|kerihenare|+1200}}
* [http://epeus.blogspot.com/ KevinMarks] (-0800/-0700)
* {{irc user|RyanKing|kingryan|-0800/-0700}}
** [http://theryanking.com/blog/archives/2006/04/19/office-hours/ Office hours]: Wednesday, 21:00 UTC
* {{irc user|Lachlan Hunt|Lachy|+1000/+1100}}
* {{irc user|Levitation|levitation[A]|+0200/+0300}}
* {{irc user|Linmic|linmic|+0800-0700}}
* {{irc user|MarkNg|madness|+0000/+0100}}
* {{irc user|Mark Mansour|Mark Mansour|+1100}}
* {{irc user|MarkNormanFrancis|Mark Norman Francis|+0000/+0100}}
* {{irc user|Maddiin|Martin Czura|+0100}}
* {{irc user|MattBowen|Matt Bowen|-0500/-0400}}
* {{irc user|MattisManzel|Mattis Manzel|+0100/+0200}}
* {{irc user|CiaranMc|McNulty|+0000/+0100}}
* <span class="vcard"><span class="fn org">[[mfbot]]</span> - a bot which logs all edits to this wiki. It appends a number with a '+' or '-' sign, to indicate the number of characters added or removed as a result of the edit.</span>
* {{irc user|Mike|Michael McCracken(mmc)|-0800/-0700}}
* {{irc user|MikeKaply|mkaply|-0600/-0500}}
* {{irc user|SteveIvy|monkinetic/redmonk|-0700}}
* {{irc user|MWTE|mwte|+0000/+0100}}
* {{irc user|RobManson|nambor|+1000}}
* {{irc user|Nelix|nelix|+1000}}
* {{irc user|neuro|neuro|<small>-unspecified-</small>}}
* {{irc user|Niekie|niekie|+0100/+0200}}
* {{irc user|NTollervey|ntoll|+0000/+0100}}
* {{irc user|Pawlik|pawlik|+0100/+0200}}
* {{irc user|Andy Pemberton|pembertona|-0500/-0400}}
* {{irc user|Phae|Phae|+0000/+0100}}
* {{irc user|pius|Pius Uzamere|+0500}}
* {{irc user|PriitLaes|plaes|+0200/+0300}}
* {{irc user|ChrisCasciano|pnhChris|-0500/-0400}}
* {{irc user|PetarPopov|popov|-0800/-0700}}
* {{irc user|Pfefferle|pfefferle|+0100/+0200}}
* {{irc user|DavidOsolkowski|qid|-0500}}
* {{irc user|RCanine|RCanine|-0500/-0400}}
* {{irc user|Remi|Remi|-0500/-0400}}
* {{irc user|ZachCarter|riah|-0500/-0400}}
* {{irc user|RobertBachmann|RobertBachmann|+0100/+0200}}
** Office hours: <s>Wednesday, 18:00-20:00 UTC</s> (Currently no office hours}}
* {{irc user|RobLinton|RobLinton|-0800/-0700}}
* {{irc user|Ronnos|Ron Kok|+0000}}
* {{irc user|SarahWorsham|sazbean|-0500/-0400}}
* {{irc user|ScottNelle|snelle|-0500/-0400}}
* {{irc user|ScottRozic|gravitas|-0500/+0100}}
* {{irc user|Dana Benson|Snowden|-0800/-0700}}
* {{irc user|SinDoc|SinDoc|+0100/+0200}}
* {{irc user|Smackman|Steve Farrell|-0800/-0700}}
* {{irc user|SpikeUK|SpikeUK|+0000/+0100}}
* {{irc user|Steve Ganz|SteveGanz|-0800/-0700}}
* {{irc user|Stii|Stii|+0200 GMT}}
* {{irc user|ReinierZ|surial|+0100 GMT}}
* {{irc user|SuperPhly|SuperPhly|-600/-500}}
* {{irc user|SyedSRahman|syedsrahman|+0530}}
* <span class="vcard"><span class="fn">sym[[User:LynX|lynX]]</span></span> or (better) [[User:LynX|lynX]] on [http://about.psyc.eu PSYC] (+0100}}
* {{irc user|DavidLehn|taaz|-0500/-0400}}
* {{irc user|Tantek|Tantek|-0800/-0700}}
* {{irc user|Wojciech|theanxy|+0100/+0200}}
* {{irc user|TheJbf|thejbf|+0100/+0200}}
* {{irc user|TobyInk|tobyink|+0000/+0100}}
* {{irc user|Trovster|trovster|-0800/-0700}}
* {{irc user|Vadania|vadania|-0600/-0700}}
* {{irc user|Vant|vant|+0900}}
* {{irc user|Victor|victor|+0100/+0200}}
* {{irc user|V-I-P|V-I-P|+0100/+0200}}
* {{irc user|KrissWatt|VoodooChild|+0000/+0100}}
* {{irc user|WebOrganics|weborganics|+0100}}
* {{irc user|JacksonWilkinson|whafro|-0500/-0400}}
* {{irc user|Richard Conyard|WhiskeyM|+0000}}
* {{irc user|Veeliam|William Lawrence|-0800/-0700}}
* {{irc user|StevenWoods|woodss|+0000 GMT}}
* {{irc user|Ianloic|yakk|-0800/-0700}}
* {{irc user|LarsStrojny|mastaYoda|+0100}}
* {{irc user|ZimbaTm|zimbatm|+0100}}
* {{irc user|FoundAtion|Foundation|-0800}}
* {{irc user|PJKix|pjkix|-0800/-700}}
* {{irc user| ChrisBroadfoot|broady|+1000}}
* {{irc user|Natalie Downe|NatBat|+0000}}
* {{irc user|Dotjay|dotjay|+0000}}
* {{irc user|Kiryl Zhybul|zkv|+0400}}
* {{irc user|ScottThorpe|Salve|-0800/-0700}}

vcard-implementations

2007-01-19T21:51:48Z

Atamido: /* N */ distinction

<h1> vCard implementations </h1>

In the development of [[hcard|hCard]] and proxies like X2V, we have discovered various behaviors and quirks of vCard implementations. See also the [[vcard-errata]].

__TOC__

== Contributors==
* Tantek Çelik
* Brian Suda
* Steve Robillard

== Microsoft Outlook ==

version? platform?

=== single import ===
Outlook (either 2003 or 2007 beta version) appears to only support one vCard per VCF. There are some
third-party products that attempt to fix this [http://www.sperrysoftware.com/Outlook/Vcard-Converter.asp]

=== URL handling ===

URL without non-standard TYPE parameter seems to be ignored.

=== ADR handling ===

Appears to not support the post-office-box sub-property of ADR.

=== Escaped Commas ===

Outlook 2003 does not strip the backslashes from escaped commas (i.e., SR-PS\, Inc.) on import.

=== Microsoft Outlook 2003 ===

The following was verified on Outlook 2003 SP2 running on Windows XP Pro SP2

==== URL ====

URL is changed to URL;HOME: and is not visible anywhere normally in Outlook. It is visible in the Contact Properties window under the "All Fields" when selecting "Frequently-used fields" from the "Select from:" drop-down box. It is also exported when exporting as a vCard.

==== ADR ====

ADR; is changed to ADR;POSTAL:

ADR; is copied to LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE: with city/state/zip changed to use carriage return and comma seperation. IE:
<pre>ADR;CHARSET=utf-8:;;address1;city;state;zip;</pre>
is changed to:
<pre>ADR;POSTAL:;;address1;city;state;zip
LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE:address1=0D=0Acity, state zip</pre>

==== N ====

When exporting a vCard, copies FN into N when N is blank. Does not do this when importing a vCard.

==== TEL ====

Drops TEL if TYPE is not specified.

TEL;TYPE=work: is changed to TEL;WORK;VOICE:

==== GEO (lack of support) ====

GEO is dropped.

==== LOGO (lack of support) ====

Will not import or export vCard image references, but does support images internally in it's own contact management system.

== Windows Address Book (WAB) ==
Version 6.00.X Win98 and Win XP Pro

=== vCard ENCODING ===
UTF-8 encoded vCard import prompts error as unrecognised vCard format. US ASCII 20127 encoded vCard successfully imported

=== ADR ===
If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

=== TEL ===
If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

=== PHOTO ===
Does not support Images

=== NOTE ===
According to the example in the RFC spec, all commas should be escaped, but WAB does not Un-escape them, leaving \, in the notes field.

== Microsoft Entourage ==

On Mac OS X. Entourage versions 10 and 11.

=== general comments ===
* Entourage versions 10 and 11 export vCard files as UTF-16, big endian, with Mac classic line endings (a single CR). The file does contain the proper UTF-16 BE BOM at the start, making identification of the file contents simpler.

* Importing vCards: Entourage 11 will look for a BOM when importing a vCard file. It respects UTF-16 BE, UTF-16 LE, and UTF-8 BOMs. With no BOM, Entourage 11 will attempt to import the vCard file as an 8-bit stream using the current system encoding (for example, Mac Roman).

* Entourage 12 (under development) is expected to have better vCard standard conformance, exporting vCard files as UTF-8 (with individual fields properly labelled with "charset=utf-8") and using Windows (CR+LF) line endings. When importing vCard files without a BOM, it wil assume UTF-8 encoding but will respect "charset=" tags if present.

== Apple Address Book ==

On Mac OS X 10.3 (Panther) and 10.4 (Tiger).

=== 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?
** Workaround: Explicitly specify the UTF-8 charset for vCard properties/fields that have non-ASCII-7 characters.
* Importing multiple vCards with the same fn/n results in duplicate entries in the Address Book. Basically, Address Book assumes that every vCard present in a single .vcf file represents a different person, even if the fn/n are the same etc.
** Workarounds:
*** Only markup one hCard per person, per page (has potential implications for [[hresume|hResume]]).
*** Have the converting application/service (e.g. X2V), do automerging of hCards with the same fn/n and generate a .vcf stream with one vCard per unique fn/n.
* Apple Address Book 4.0.4 (Mac OS X 10.4) exports vCard files as UTF-16 big endian with no BOM and Mac (CR) line endings, if the vCard record contains any non-ASCII data (for example Japanese characters). If the entire vCard record can be represented in ASCII, it is exported as an ASCII encoded file with Windows (CR+LF) line endings.

=== organization vs. individual ===

Summary: FN==ORG organization semantic supported for both import and export.

For organization contact info, sets the FN and ORG to the name of the organization and N to empty on exported vCards.

Also treats imported vCards like that as organization contact info cards visibly in the UI.

=== geo (lack of support) ===

The GEO field is ignored on imported vCards. It is only saved as part of the NOTE.

=== source (lack of support) ===

The SOURCE property is not supported on imported vCards. It is only saved as part of the NOTE.

=== logo (lack of support) ===

The LOGO property is totally ignored and not even saved as part of the NOTE.

=== photo (limitations) ===

The PHOTO property can only take inline encoded data. URL values for are ignored.

=== url (limitations) ===

Only ONE URL property value is supported (whereas multiple *should* be supported, just like EMAIL).

=== adr (behaviour) ===

If you do NOT specify which type of address information it is (like HOME or WORK) it is assumed to be a WORK address.

=== categories (behaviour) ===

Behavior confirmed on versions:
* default on OSX.3
* Version 4.03 (483) on OSX.

Summary: Exports native "Groups" as vCard CATEGORIES. Ignores CATEGORIES field when importing a vCard.

The UI lets you create distinct "Groups" which you can then drag contacts into. Contacts can be in more than one group. Upon exporting a contact that is in one or more Groups, those Groups are listed in the CATEGORIES field.

However, when importing vCards, the CATEGORIES field is totally ignored by Address Book.
# It does not add vCards with a category that matches a current Group to that Group.
# It does not create new Groups for vCards with new categories.
# It does not even add the CATEGORIES to the end of the notes field.
Though presumably it SHOULD do #1 and #2. Would also be nice if it simply let you edit the groups/categories for a contact simply as a list of tags for that contact.

== Evolution ==

On Linux.

=== geo (lack of support) ===

* ichigo, Frederic to fill in details

== Nokia series 60 address book ==

=== Line endings ===

The Contacts application on Nokia series 60 handsets will only open vCards with Windows (\r\n) line endings. Any other line ending styles will cause an error message.

This is actually reasonable behaviour because the vCard spec explicitly states \r\n should be used, but many applications will accept \n delimited vCards without complaint, and may microformat services produce \n delimited output.

vcard-implementations

2007-01-19T21:48:19Z

Atamido: /* GEO */

<h1> vCard implementations </h1>

In the development of [[hcard|hCard]] and proxies like X2V, we have discovered various behaviors and quirks of vCard implementations. See also the [[vcard-errata]].

__TOC__

== Contributors==
* Tantek Çelik
* Brian Suda
* Steve Robillard

== Microsoft Outlook ==

version? platform?

=== single import ===
Outlook (either 2003 or 2007 beta version) appears to only support one vCard per VCF. There are some
third-party products that attempt to fix this [http://www.sperrysoftware.com/Outlook/Vcard-Converter.asp]

=== URL handling ===

URL without non-standard TYPE parameter seems to be ignored.

=== ADR handling ===

Appears to not support the post-office-box sub-property of ADR.

=== Escaped Commas ===

Outlook 2003 does not strip the backslashes from escaped commas (i.e., SR-PS\, Inc.) on import.

=== Microsoft Outlook 2003 ===

The following was verified on Outlook 2003 SP2 running on Windows XP Pro SP2

==== URL ====

URL is changed to URL;HOME: and is not visible anywhere normally in Outlook. It is visible in the Contact Properties window under the "All Fields" when selecting "Frequently-used fields" from the "Select from:" drop-down box. It is also exported when exporting as a vCard.

==== ADR ====

ADR; is changed to ADR;POSTAL:

ADR; is copied to LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE: with city/state/zip changed to use carriage return and comma seperation. IE:
<pre>ADR;CHARSET=utf-8:;;address1;city;state;zip;</pre>
is changed to:
<pre>ADR;POSTAL:;;address1;city;state;zip
LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE:address1=0D=0Acity, state zip</pre>

==== N ====

Copies FN into N when N is blank.

==== TEL ====

Drops TEL if TYPE is not specified.

TEL;TYPE=work: is changed to TEL;WORK;VOICE:

==== GEO (lack of support) ====

GEO is dropped.

==== LOGO (lack of support) ====

Will not import or export vCard image references, but does support images internally in it's own contact management system.

== Windows Address Book (WAB) ==
Version 6.00.X Win98 and Win XP Pro

=== vCard ENCODING ===
UTF-8 encoded vCard import prompts error as unrecognised vCard format. US ASCII 20127 encoded vCard successfully imported

=== ADR ===
If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

=== TEL ===
If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

=== PHOTO ===
Does not support Images

=== NOTE ===
According to the example in the RFC spec, all commas should be escaped, but WAB does not Un-escape them, leaving \, in the notes field.

== Microsoft Entourage ==

On Mac OS X. Entourage versions 10 and 11.

=== general comments ===
* Entourage versions 10 and 11 export vCard files as UTF-16, big endian, with Mac classic line endings (a single CR). The file does contain the proper UTF-16 BE BOM at the start, making identification of the file contents simpler.

* Importing vCards: Entourage 11 will look for a BOM when importing a vCard file. It respects UTF-16 BE, UTF-16 LE, and UTF-8 BOMs. With no BOM, Entourage 11 will attempt to import the vCard file as an 8-bit stream using the current system encoding (for example, Mac Roman).

* Entourage 12 (under development) is expected to have better vCard standard conformance, exporting vCard files as UTF-8 (with individual fields properly labelled with "charset=utf-8") and using Windows (CR+LF) line endings. When importing vCard files without a BOM, it wil assume UTF-8 encoding but will respect "charset=" tags if present.

== Apple Address Book ==

On Mac OS X 10.3 (Panther) and 10.4 (Tiger).

=== 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?
** Workaround: Explicitly specify the UTF-8 charset for vCard properties/fields that have non-ASCII-7 characters.
* Importing multiple vCards with the same fn/n results in duplicate entries in the Address Book. Basically, Address Book assumes that every vCard present in a single .vcf file represents a different person, even if the fn/n are the same etc.
** Workarounds:
*** Only markup one hCard per person, per page (has potential implications for [[hresume|hResume]]).
*** Have the converting application/service (e.g. X2V), do automerging of hCards with the same fn/n and generate a .vcf stream with one vCard per unique fn/n.
* Apple Address Book 4.0.4 (Mac OS X 10.4) exports vCard files as UTF-16 big endian with no BOM and Mac (CR) line endings, if the vCard record contains any non-ASCII data (for example Japanese characters). If the entire vCard record can be represented in ASCII, it is exported as an ASCII encoded file with Windows (CR+LF) line endings.

=== organization vs. individual ===

Summary: FN==ORG organization semantic supported for both import and export.

For organization contact info, sets the FN and ORG to the name of the organization and N to empty on exported vCards.

Also treats imported vCards like that as organization contact info cards visibly in the UI.

=== geo (lack of support) ===

The GEO field is ignored on imported vCards. It is only saved as part of the NOTE.

=== source (lack of support) ===

The SOURCE property is not supported on imported vCards. It is only saved as part of the NOTE.

=== logo (lack of support) ===

The LOGO property is totally ignored and not even saved as part of the NOTE.

=== photo (limitations) ===

The PHOTO property can only take inline encoded data. URL values for are ignored.

=== url (limitations) ===

Only ONE URL property value is supported (whereas multiple *should* be supported, just like EMAIL).

=== adr (behaviour) ===

If you do NOT specify which type of address information it is (like HOME or WORK) it is assumed to be a WORK address.

=== categories (behaviour) ===

Behavior confirmed on versions:
* default on OSX.3
* Version 4.03 (483) on OSX.

Summary: Exports native "Groups" as vCard CATEGORIES. Ignores CATEGORIES field when importing a vCard.

The UI lets you create distinct "Groups" which you can then drag contacts into. Contacts can be in more than one group. Upon exporting a contact that is in one or more Groups, those Groups are listed in the CATEGORIES field.

However, when importing vCards, the CATEGORIES field is totally ignored by Address Book.
# It does not add vCards with a category that matches a current Group to that Group.
# It does not create new Groups for vCards with new categories.
# It does not even add the CATEGORIES to the end of the notes field.
Though presumably it SHOULD do #1 and #2. Would also be nice if it simply let you edit the groups/categories for a contact simply as a list of tags for that contact.

== Evolution ==

On Linux.

=== geo (lack of support) ===

* ichigo, Frederic to fill in details

== Nokia series 60 address book ==

=== Line endings ===

The Contacts application on Nokia series 60 handsets will only open vCards with Windows (\r\n) line endings. Any other line ending styles will cause an error message.

This is actually reasonable behaviour because the vCard spec explicitly states \r\n should be used, but many applications will accept \n delimited vCards without complaint, and may microformat services produce \n delimited output.

vcard-implementations

2007-01-19T21:47:12Z

Atamido: /* LOGO */

<h1> vCard implementations </h1>

In the development of [[hcard|hCard]] and proxies like X2V, we have discovered various behaviors and quirks of vCard implementations. See also the [[vcard-errata]].

__TOC__

== Contributors==
* Tantek Çelik
* Brian Suda
* Steve Robillard

== Microsoft Outlook ==

version? platform?

=== single import ===
Outlook (either 2003 or 2007 beta version) appears to only support one vCard per VCF. There are some
third-party products that attempt to fix this [http://www.sperrysoftware.com/Outlook/Vcard-Converter.asp]

=== URL handling ===

URL without non-standard TYPE parameter seems to be ignored.

=== ADR handling ===

Appears to not support the post-office-box sub-property of ADR.

=== Escaped Commas ===

Outlook 2003 does not strip the backslashes from escaped commas (i.e., SR-PS\, Inc.) on import.

=== Microsoft Outlook 2003 ===

The following was verified on Outlook 2003 SP2 running on Windows XP Pro SP2

==== URL ====

URL is changed to URL;HOME: and is not visible anywhere normally in Outlook. It is visible in the Contact Properties window under the "All Fields" when selecting "Frequently-used fields" from the "Select from:" drop-down box. It is also exported when exporting as a vCard.

==== ADR ====

ADR; is changed to ADR;POSTAL:

ADR; is copied to LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE: with city/state/zip changed to use carriage return and comma seperation. IE:
<pre>ADR;CHARSET=utf-8:;;address1;city;state;zip;</pre>
is changed to:
<pre>ADR;POSTAL:;;address1;city;state;zip
LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE:address1=0D=0Acity, state zip</pre>

==== N ====

Copies FN into N when N is blank.

==== TEL ====

Drops TEL if TYPE is not specified.

TEL;TYPE=work: is changed to TEL;WORK;VOICE:

==== GEO ====

GEO is dropped.

==== LOGO (lack of support) ====

Will not import or export vCard image references, but does support images internally in it's own contact management system.

== Windows Address Book (WAB) ==
Version 6.00.X Win98 and Win XP Pro

=== vCard ENCODING ===
UTF-8 encoded vCard import prompts error as unrecognised vCard format. US ASCII 20127 encoded vCard successfully imported

=== ADR ===
If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

=== TEL ===
If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

=== PHOTO ===
Does not support Images

=== NOTE ===
According to the example in the RFC spec, all commas should be escaped, but WAB does not Un-escape them, leaving \, in the notes field.

== Microsoft Entourage ==

On Mac OS X. Entourage versions 10 and 11.

=== general comments ===
* Entourage versions 10 and 11 export vCard files as UTF-16, big endian, with Mac classic line endings (a single CR). The file does contain the proper UTF-16 BE BOM at the start, making identification of the file contents simpler.

* Importing vCards: Entourage 11 will look for a BOM when importing a vCard file. It respects UTF-16 BE, UTF-16 LE, and UTF-8 BOMs. With no BOM, Entourage 11 will attempt to import the vCard file as an 8-bit stream using the current system encoding (for example, Mac Roman).

* Entourage 12 (under development) is expected to have better vCard standard conformance, exporting vCard files as UTF-8 (with individual fields properly labelled with "charset=utf-8") and using Windows (CR+LF) line endings. When importing vCard files without a BOM, it wil assume UTF-8 encoding but will respect "charset=" tags if present.

== Apple Address Book ==

On Mac OS X 10.3 (Panther) and 10.4 (Tiger).

=== 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?
** Workaround: Explicitly specify the UTF-8 charset for vCard properties/fields that have non-ASCII-7 characters.
* Importing multiple vCards with the same fn/n results in duplicate entries in the Address Book. Basically, Address Book assumes that every vCard present in a single .vcf file represents a different person, even if the fn/n are the same etc.
** Workarounds:
*** Only markup one hCard per person, per page (has potential implications for [[hresume|hResume]]).
*** Have the converting application/service (e.g. X2V), do automerging of hCards with the same fn/n and generate a .vcf stream with one vCard per unique fn/n.
* Apple Address Book 4.0.4 (Mac OS X 10.4) exports vCard files as UTF-16 big endian with no BOM and Mac (CR) line endings, if the vCard record contains any non-ASCII data (for example Japanese characters). If the entire vCard record can be represented in ASCII, it is exported as an ASCII encoded file with Windows (CR+LF) line endings.

=== organization vs. individual ===

Summary: FN==ORG organization semantic supported for both import and export.

For organization contact info, sets the FN and ORG to the name of the organization and N to empty on exported vCards.

Also treats imported vCards like that as organization contact info cards visibly in the UI.

=== geo (lack of support) ===

The GEO field is ignored on imported vCards. It is only saved as part of the NOTE.

=== source (lack of support) ===

The SOURCE property is not supported on imported vCards. It is only saved as part of the NOTE.

=== logo (lack of support) ===

The LOGO property is totally ignored and not even saved as part of the NOTE.

=== photo (limitations) ===

The PHOTO property can only take inline encoded data. URL values for are ignored.

=== url (limitations) ===

Only ONE URL property value is supported (whereas multiple *should* be supported, just like EMAIL).

=== adr (behaviour) ===

If you do NOT specify which type of address information it is (like HOME or WORK) it is assumed to be a WORK address.

=== categories (behaviour) ===

Behavior confirmed on versions:
* default on OSX.3
* Version 4.03 (483) on OSX.

Summary: Exports native "Groups" as vCard CATEGORIES. Ignores CATEGORIES field when importing a vCard.

The UI lets you create distinct "Groups" which you can then drag contacts into. Contacts can be in more than one group. Upon exporting a contact that is in one or more Groups, those Groups are listed in the CATEGORIES field.

However, when importing vCards, the CATEGORIES field is totally ignored by Address Book.
# It does not add vCards with a category that matches a current Group to that Group.
# It does not create new Groups for vCards with new categories.
# It does not even add the CATEGORIES to the end of the notes field.
Though presumably it SHOULD do #1 and #2. Would also be nice if it simply let you edit the groups/categories for a contact simply as a list of tags for that contact.

== Evolution ==

On Linux.

=== geo (lack of support) ===

* ichigo, Frederic to fill in details

== Nokia series 60 address book ==

=== Line endings ===

The Contacts application on Nokia series 60 handsets will only open vCards with Windows (\r\n) line endings. Any other line ending styles will cause an error message.

This is actually reasonable behaviour because the vCard spec explicitly states \r\n should be used, but many applications will accept \n delimited vCards without complaint, and may microformat services produce \n delimited output.

vcard-implementations

2007-01-19T21:42:04Z

Atamido: /* Microsoft Outlook 2003 */

<h1> vCard implementations </h1>

In the development of [[hcard|hCard]] and proxies like X2V, we have discovered various behaviors and quirks of vCard implementations. See also the [[vcard-errata]].

__TOC__

== Contributors==
* Tantek Çelik
* Brian Suda
* Steve Robillard

== Microsoft Outlook ==

version? platform?

=== single import ===
Outlook (either 2003 or 2007 beta version) appears to only support one vCard per VCF. There are some
third-party products that attempt to fix this [http://www.sperrysoftware.com/Outlook/Vcard-Converter.asp]

=== URL handling ===

URL without non-standard TYPE parameter seems to be ignored.

=== ADR handling ===

Appears to not support the post-office-box sub-property of ADR.

=== Escaped Commas ===

Outlook 2003 does not strip the backslashes from escaped commas (i.e., SR-PS\, Inc.) on import.

=== Microsoft Outlook 2003 ===

The following was verified on Outlook 2003 SP2 running on Windows XP Pro SP2

==== URL ====

URL is changed to URL;HOME: and is not visible anywhere normally in Outlook. It is visible in the Contact Properties window under the "All Fields" when selecting "Frequently-used fields" from the "Select from:" drop-down box. It is also exported when exporting as a vCard.

==== ADR ====

ADR; is changed to ADR;POSTAL:

ADR; is copied to LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE: with city/state/zip changed to use carriage return and comma seperation. IE:
<pre>ADR;CHARSET=utf-8:;;address1;city;state;zip;</pre>
is changed to:
<pre>ADR;POSTAL:;;address1;city;state;zip
LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE:address1=0D=0Acity, state zip</pre>

==== N ====

Copies FN into N when N is blank.

==== TEL ====

Drops TEL if TYPE is not specified.

TEL;TYPE=work: is changed to TEL;WORK;VOICE:

==== GEO ====

GEO is dropped.

==== LOGO ====

LOGO;VALUE=uri: is dropped.

== Windows Address Book (WAB) ==
Version 6.00.X Win98 and Win XP Pro

=== vCard ENCODING ===
UTF-8 encoded vCard import prompts error as unrecognised vCard format. US ASCII 20127 encoded vCard successfully imported

=== ADR ===
If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

=== TEL ===
If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

=== PHOTO ===
Does not support Images

=== NOTE ===
According to the example in the RFC spec, all commas should be escaped, but WAB does not Un-escape them, leaving \, in the notes field.

== Microsoft Entourage ==

On Mac OS X. Entourage versions 10 and 11.

=== general comments ===
* Entourage versions 10 and 11 export vCard files as UTF-16, big endian, with Mac classic line endings (a single CR). The file does contain the proper UTF-16 BE BOM at the start, making identification of the file contents simpler.

* Importing vCards: Entourage 11 will look for a BOM when importing a vCard file. It respects UTF-16 BE, UTF-16 LE, and UTF-8 BOMs. With no BOM, Entourage 11 will attempt to import the vCard file as an 8-bit stream using the current system encoding (for example, Mac Roman).

* Entourage 12 (under development) is expected to have better vCard standard conformance, exporting vCard files as UTF-8 (with individual fields properly labelled with "charset=utf-8") and using Windows (CR+LF) line endings. When importing vCard files without a BOM, it wil assume UTF-8 encoding but will respect "charset=" tags if present.

== Apple Address Book ==

On Mac OS X 10.3 (Panther) and 10.4 (Tiger).

=== 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?
** Workaround: Explicitly specify the UTF-8 charset for vCard properties/fields that have non-ASCII-7 characters.
* Importing multiple vCards with the same fn/n results in duplicate entries in the Address Book. Basically, Address Book assumes that every vCard present in a single .vcf file represents a different person, even if the fn/n are the same etc.
** Workarounds:
*** Only markup one hCard per person, per page (has potential implications for [[hresume|hResume]]).
*** Have the converting application/service (e.g. X2V), do automerging of hCards with the same fn/n and generate a .vcf stream with one vCard per unique fn/n.
* Apple Address Book 4.0.4 (Mac OS X 10.4) exports vCard files as UTF-16 big endian with no BOM and Mac (CR) line endings, if the vCard record contains any non-ASCII data (for example Japanese characters). If the entire vCard record can be represented in ASCII, it is exported as an ASCII encoded file with Windows (CR+LF) line endings.

=== organization vs. individual ===

Summary: FN==ORG organization semantic supported for both import and export.

For organization contact info, sets the FN and ORG to the name of the organization and N to empty on exported vCards.

Also treats imported vCards like that as organization contact info cards visibly in the UI.

=== geo (lack of support) ===

The GEO field is ignored on imported vCards. It is only saved as part of the NOTE.

=== source (lack of support) ===

The SOURCE property is not supported on imported vCards. It is only saved as part of the NOTE.

=== logo (lack of support) ===

The LOGO property is totally ignored and not even saved as part of the NOTE.

=== photo (limitations) ===

The PHOTO property can only take inline encoded data. URL values for are ignored.

=== url (limitations) ===

Only ONE URL property value is supported (whereas multiple *should* be supported, just like EMAIL).

=== adr (behaviour) ===

If you do NOT specify which type of address information it is (like HOME or WORK) it is assumed to be a WORK address.

=== categories (behaviour) ===

Behavior confirmed on versions:
* default on OSX.3
* Version 4.03 (483) on OSX.

Summary: Exports native "Groups" as vCard CATEGORIES. Ignores CATEGORIES field when importing a vCard.

The UI lets you create distinct "Groups" which you can then drag contacts into. Contacts can be in more than one group. Upon exporting a contact that is in one or more Groups, those Groups are listed in the CATEGORIES field.

However, when importing vCards, the CATEGORIES field is totally ignored by Address Book.
# It does not add vCards with a category that matches a current Group to that Group.
# It does not create new Groups for vCards with new categories.
# It does not even add the CATEGORIES to the end of the notes field.
Though presumably it SHOULD do #1 and #2. Would also be nice if it simply let you edit the groups/categories for a contact simply as a list of tags for that contact.

== Evolution ==

On Linux.

=== geo (lack of support) ===

* ichigo, Frederic to fill in details

== Nokia series 60 address book ==

=== Line endings ===

The Contacts application on Nokia series 60 handsets will only open vCards with Windows (\r\n) line endings. Any other line ending styles will cause an error message.

This is actually reasonable behaviour because the vCard spec explicitly states \r\n should be used, but many applications will accept \n delimited vCards without complaint, and may microformat services produce \n delimited output.

vcard-implementations

2007-01-19T21:38:59Z

Atamido: /* Microsoft Outlook */

<h1> vCard implementations </h1>

In the development of [[hcard|hCard]] and proxies like X2V, we have discovered various behaviors and quirks of vCard implementations. See also the [[vcard-errata]].

__TOC__

== Contributors==
* Tantek Çelik
* Brian Suda
* Steve Robillard

== Microsoft Outlook ==

version? platform?

=== single import ===
Outlook (either 2003 or 2007 beta version) appears to only support one vCard per VCF. There are some
third-party products that attempt to fix this [http://www.sperrysoftware.com/Outlook/Vcard-Converter.asp]

=== URL handling ===

URL without non-standard TYPE parameter seems to be ignored.

=== ADR handling ===

Appears to not support the post-office-box sub-property of ADR.

=== Escaped Commas ===

Outlook 2003 does not strip the backslashes from escaped commas (i.e., SR-PS\, Inc.) on import.

=== Microsoft Outlook 2003 ===

The following was verified on Outlook 2003 SP2 running on Windows XP Pro SP2

==== URL ====

URL is changed to URL;HOME: and is not visible anywhere normally in Outlook. It is visible in the Contact Properties window under the "All Fields" when selecting "Frequently-used fields" from the "Select from:" drop-down box. It is also exported when exporting as a vCard.

==== ADR ====

ADR; is changed to ADR;POSTAL:

ADR; is copied to LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE: with city/state/zip changed to use carriage return and comma seperation. IE:
<pre>ADR;CHARSET=utf-8:;;address1;city;state;zip;</pre>
is changed to:
<pre>ADR;POSTAL:;;address1;city;state;zip
LABEL;POSTAL;ENCODING=QUOTED-PRINTABLE:address1=0D=0Acity, state zip</pre>

==== N ====

Copies FN into N when N is blank.

==== TEL ====

Drops TEL if TYPE is not specified.

TEL;TYPE=work: is changed to TEL;WORK;VOICE:

==== GEO ====

GEO is dropped.

== Windows Address Book (WAB) ==
Version 6.00.X Win98 and Win XP Pro

=== vCard ENCODING ===
UTF-8 encoded vCard import prompts error as unrecognised vCard format. US ASCII 20127 encoded vCard successfully imported

=== ADR ===
If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

=== TEL ===
If you do NOT specify TYPE=HOME,WORK,... then no address information is imported

=== PHOTO ===
Does not support Images

=== NOTE ===
According to the example in the RFC spec, all commas should be escaped, but WAB does not Un-escape them, leaving \, in the notes field.

== Microsoft Entourage ==

On Mac OS X. Entourage versions 10 and 11.

=== general comments ===
* Entourage versions 10 and 11 export vCard files as UTF-16, big endian, with Mac classic line endings (a single CR). The file does contain the proper UTF-16 BE BOM at the start, making identification of the file contents simpler.

* Importing vCards: Entourage 11 will look for a BOM when importing a vCard file. It respects UTF-16 BE, UTF-16 LE, and UTF-8 BOMs. With no BOM, Entourage 11 will attempt to import the vCard file as an 8-bit stream using the current system encoding (for example, Mac Roman).

* Entourage 12 (under development) is expected to have better vCard standard conformance, exporting vCard files as UTF-8 (with individual fields properly labelled with "charset=utf-8") and using Windows (CR+LF) line endings. When importing vCard files without a BOM, it wil assume UTF-8 encoding but will respect "charset=" tags if present.

== Apple Address Book ==

On Mac OS X 10.3 (Panther) and 10.4 (Tiger).

=== 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?
** Workaround: Explicitly specify the UTF-8 charset for vCard properties/fields that have non-ASCII-7 characters.
* Importing multiple vCards with the same fn/n results in duplicate entries in the Address Book. Basically, Address Book assumes that every vCard present in a single .vcf file represents a different person, even if the fn/n are the same etc.
** Workarounds:
*** Only markup one hCard per person, per page (has potential implications for [[hresume|hResume]]).
*** Have the converting application/service (e.g. X2V), do automerging of hCards with the same fn/n and generate a .vcf stream with one vCard per unique fn/n.
* Apple Address Book 4.0.4 (Mac OS X 10.4) exports vCard files as UTF-16 big endian with no BOM and Mac (CR) line endings, if the vCard record contains any non-ASCII data (for example Japanese characters). If the entire vCard record can be represented in ASCII, it is exported as an ASCII encoded file with Windows (CR+LF) line endings.

=== organization vs. individual ===

Summary: FN==ORG organization semantic supported for both import and export.

For organization contact info, sets the FN and ORG to the name of the organization and N to empty on exported vCards.

Also treats imported vCards like that as organization contact info cards visibly in the UI.

=== geo (lack of support) ===

The GEO field is ignored on imported vCards. It is only saved as part of the NOTE.

=== source (lack of support) ===

The SOURCE property is not supported on imported vCards. It is only saved as part of the NOTE.

=== logo (lack of support) ===

The LOGO property is totally ignored and not even saved as part of the NOTE.

=== photo (limitations) ===

The PHOTO property can only take inline encoded data. URL values for are ignored.

=== url (limitations) ===

Only ONE URL property value is supported (whereas multiple *should* be supported, just like EMAIL).

=== adr (behaviour) ===

If you do NOT specify which type of address information it is (like HOME or WORK) it is assumed to be a WORK address.

=== categories (behaviour) ===

Behavior confirmed on versions:
* default on OSX.3
* Version 4.03 (483) on OSX.

Summary: Exports native "Groups" as vCard CATEGORIES. Ignores CATEGORIES field when importing a vCard.

The UI lets you create distinct "Groups" which you can then drag contacts into. Contacts can be in more than one group. Upon exporting a contact that is in one or more Groups, those Groups are listed in the CATEGORIES field.

However, when importing vCards, the CATEGORIES field is totally ignored by Address Book.
# It does not add vCards with a category that matches a current Group to that Group.
# It does not create new Groups for vCards with new categories.
# It does not even add the CATEGORIES to the end of the notes field.
Though presumably it SHOULD do #1 and #2. Would also be nice if it simply let you edit the groups/categories for a contact simply as a list of tags for that contact.

== Evolution ==

On Linux.

=== geo (lack of support) ===

* ichigo, Frederic to fill in details

== Nokia series 60 address book ==

=== Line endings ===

The Contacts application on Nokia series 60 handsets will only open vCards with Windows (\r\n) line endings. Any other line ending styles will cause an error message.

This is actually reasonable behaviour because the vCard spec explicitly states \r\n should be used, but many applications will accept \n delimited vCards without complaint, and may microformat services produce \n delimited output.

existing-classes

2006-05-03T16:05:55Z

Atamido: Added the class names from hResume.

<table>
<tr>
<th>Term</th>
<th>Parents</th>
<th>Children</th>
<th>Origin</th>
<th>Quick Definition</th>
</tr>
<tr>
<td>adr</td>
<td>vcard</td>
<td> country-name, extended-address, locality, postal-code, post-office-box, street-address,region, type, value </td>
<td>[[hcard|hCard]] </td>
<td>Address of the object. </td>
</tr>
<tr>
<td>affiliation</td>
<td>hresume </td>
<td></td>
<td>[[hresume|hResume]]</td>
<td>Is used along with an hcard of the organization to indicate a relationship or affiliation.</td>
</tr>
<tr>
<td>bday </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>The birth date of the object. </td>
</tr>
<tr>
<td>category </td>
<td>vcard, hreview </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Application category of the object.</td>
</tr>
<tr>
<td>class </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>The access classification of the object. For example, public or private. </td>
</tr>
<tr>
<td>contact</td>
<td>hresume </td>
<td></td>
<td>[[hresume|hResume]]</td>
<td>Current contact info of the object. The <code class="element"><address></code> with [[hCard]].</td>
</tr>
<tr>
<td>country-name </td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Name of the country for this particular address. </td>
</tr>
<tr>
<td>description</td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>Full text of the description. (Not to be confused with the much longer "summary")</td>
</tr>
<tr>
<td>dtend </td>
<td>vevent </td>
<td></td>
<td>[[hcalendar|hCalendar]] </td>
<td>Ending date of the object. </td>
</tr>
<tr>
<td>dtreviewed</td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>Date the review was written, NOT necessarily when the review took place. </td>
</tr>
<tr>
<td>dtstart</td>
<td>vevent </td>
<td></td>
<td>[[hcalendar|hCalendar]] </td>
<td>Starting date of the object. (Not to be confused with bday) </td>
</tr>
<tr>
<td>education</td>
<td>hresume </td>
<td></td>
<td>[[hresume|hResume]]</td>
<td>Is applied to an hcalendar event to indicate time spent being educated.</td>
</tr>
<tr>
<td>email </td>
<td>vcard, hreview </td>
<td> type, value</td>
<td>[[hcard|hCard]] </td><td>This object's email address. </td>
</tr>
<tr>
<td>experience</td>
<td>hresume </td>
<td></td>
<td>[[hresume|hResume]]</td>
<td>Is applied to an hcalendar event. Job titles/positions should use an hCard.</td>
</tr>
<tr>
<td>extended-address</td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Extended address for this particular address.</td>
</tr>
<tr>
<td>fn</td>
<td>vcard, hreview </td>
<td></td>
<td>[[hcard|hCard]]</td>
<td>The name of the object. </td>
</tr>
<tr>
<td>geo </td>
<td>vcard</td>
<td>latitude, longitude </td>
<td>[[hcard|hCard]] </td>
<td>Geographical coordinates of the object. </td>
</tr>
<tr>
<td>hresume </td>
<td>*webpage</td>
<td>affiliation, contact, education, experience, publications, skill, summary </td>
<td>[[hresume|hResume]]</td>
<td>The resume of some object. </td>
</tr>
<tr>
<td>hreview </td>
<td>*webpage</td>
<td></td>
<td>[[hreview|hReview]]</td>
<td>A review of some object. </td>
</tr>
<tr>
<td>item </td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>The item that the object exists for. For example, a review about Coca-Cola would list "Coca-Cola" as the item. </td>
</tr>
<tr>
<td>key </td>
<td>vcard</td>
<td>type, value </td>
<td>[[hcard|hCard]] </td>
<td>Public key of the object</td>
</tr>
<tr>
<td>label </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Formatting to be used by a delivery address label. </td>
</tr>
<tr>
<td>latitude </td>
<td>geo</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>The latitude coordinates of the object. </td>
</tr>
<tr>
<td>locality </td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Locality for this particular address. </td>
</tr>
<tr>
<td>location</td>
<td>vevent </td>
<td></td>
<td>[[hcalendar|hCalendar]] </td>
<td>Intended venue of object. (Not to be confused with adr) </td>
</tr>
<tr>
<td>logo </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Object's logo. </td>
</tr>
<tr>
<td>longitude</td>
<td>geo</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>The longitude coordinates of the object. </td>
</tr>
<tr>
<td>mailer </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Email software used by the object. </td>
</tr>
<tr>
<td>n </td>
<td>vcard</td>
<td> additional-name, family-name, given-name, honorific-prefix, honorific-suffix, nickname</td>
<td>[[hcard|hCard]] </td><td>The name of the unit </td>
</tr>
<tr>
<td>note </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Supplemental information about the object. </td>
</tr>
<tr>
<td>org </td>
<td>vcard</td>
<td>organization-name, organization-unit</td>
<td>[[hcard|hCard]] </td><td>The organization or company of the object. </td>
</tr>
<tr>
<td>organization-name </td>
<td>org</td>
<td></td>
<td>[[hcard|hCard]] </td><td>The name of the organization or company of the object. </td>
</tr>
<tr>
<td>organization-unit </td>
<td>org</td>
<td></td>
<td>[[hcard|hCard]] </td><td>The unit or department of the object. </td>
</tr>
<tr>
<td>permalink </td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>A link to the object. This link should never become invalid. Used in <a> </td>
</tr>
<tr>
<td>photo </td>
<td>vcard, hreview </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>A photo of the object. Used in <img> </td>
</tr>
<tr>
<td>post-office-box </td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Post office box number of this particular address. </td>
</tr>
<tr>
<td>postal-code</td>
<td>adr, value</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Postal code for this particular address. </td>
</tr>
<tr>
<td>profile</td>
<td>*webpage</td>
<td></td>
<td>XMDP</td>
<td>Contains metadata types and definitions. Used in <dl> </td>
</tr>
<tr>
<td>publications</td>
<td>hresume </td>
<td></td>
<td>[[hresume|hResume]]</td>
<td>Publications the object has produced. Just use <code class="element"><cite></code>. When there is a [[citation]] microformat, then that can be used in combination with the cite element to further markup the components of the citation.</td>
</tr>
<tr>
<td>rating </td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>Rating of 1-5 or 0-10 of the object. </td>
</tr>
<tr>
<td>region</td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Region of this particular address. </td>
</tr>
<tr>
<td>rev </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]]</td>
<td>Specifies revision of the [[hcard|hCard]]. </td>
</tr>
<tr>
<td>reviewer </td>
<td>hreview</td>
<td>vcard</td>
<td>[[hreview|hReview]] </td>
<td>Person that wrote the review of the object. </td>
</tr>
<tr>
<td>role </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Information regarding the role of the object. </td>
</tr>
<tr>
<td>skill</td>
<td>hresume </td>
<td></td>
<td>[[hresume|hResume]]</td>
<td>Phrases or keywords, using the rel-tag microformat with the class name 'skill', to indicate certain skills or abilities the object posseses.</td>
</tr>
<tr>
<td>sort-string </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td><td>String used to sort this object in an alphabetical list. </td>
</tr>
<tr>
<td>sound </td>
<td>*any</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Audio reading back another element's content. By default, the "fn". </td>
</tr>
<tr>
<td>street-address </td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]]</td>
<td>Street address of this particular address. </td>
</tr>
<tr>
<td>summary </td>
<td>vevent , hreview, hresume </td>
<td></td>
<td>[[hcalendar|hCalendar]] </td>
<td>A short summary or subject for the object. </td>
</tr>
<tr>
<td>tel </td>
<td>vcard</td>
<td> type, value</td>
<td>[[hcard|hCard]] </td>
<td>Telephone number of the object </td>
</tr>
<tr>
<td>title </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Job title or functional position of the object.</td>
</tr>
<tr>
<td>type </td>
<td>adr, email, tel </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Defines a type of the parent element. For instance a type of telephone number such as home or work.. Used in conjunction with "value". </td>
</tr>
<tr>
<td>tz </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>The timezone the object is in. </td>
</tr>
<tr>
<td>uid </td>
<td>*any</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Globally unique identifier associated with the object, or one of the object's properties. </td>
</tr>
<tr>
<td>url </td>
<td>vcard, vevent , hreview </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>A link to the this object's home page or extended profile. Used in <a> </td>
</tr>
<tr>
<td>value </td>
<td>adr, email, tel </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Used in conjunction with "type". The actual value of a particular type. For instance a telephone number of type work such as +1.415.555.1212. </td>
</tr>
<tr>
<td>vcalendar</td>
<td>*webpage</td>
<td>vevent</td>
<td>[[hcalendar|hCalendar]] </td>
<td>A list of calendar events. </td>
</tr>
<tr>
<td>vcard </td>
<td>*webpage, vevent </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Indicates that this element and all containing elements are part of the [[hcard|hCard]] microformat. </td>
</tr>
<tr>
<td> vevent </td>
<td>*webpage, vcalendar </td>
<td></td>
<td>[[hcalendar|hCalendar]]</td>
<td>Indicates that this element and all contained elements are part of the [[hcalendar|hCalendar]] format. </td>
</tr>
<tr>
<td>version</td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>Version of the format used for the object. </td>
</tr>
<tr>
<td>xoxo </td>
<td>*webpage</td>
<td></td>
<td>[[xoxo|XOXO]]</td>
<td>An outline of data. Used in <ul> and <ol>. </td>
</tr>
</table>

existing-classes

2006-03-16T15:27:30Z

Atamido: Fixed hcard, hreview, xoxo links

<table>
<tr>
<th>Term</th>
<th>Parents</th>
<th>Children</th>
<th>Origin</th>
<th>Quick Definition</th>
</tr>
<tr>
<td>adr</td>
<td>vcard</td>
<td> country-name, extended-address, locality, postal-code, post-office-box, street-address,region, type, value </td>
<td>[[hcard|hCard]] </td>
<td>Address of the object. </td>
</tr>
<tr>
<td>bday </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>The birth date of the object. </td>
</tr>
<tr>
<td>category </td>
<td>vcard, hreview </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Application category of the object.</td>
</tr>
<tr>
<td>class </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>The access classification of the object. For example, public or private. </td>
</tr>
<tr>
<td>country-name </td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Name of the country for this particular address. </td>
</tr>
<tr>
<td>description</td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>Full text of the description. (Not to be confused with the much longer "summary")</td>
</tr>
<tr>
<td>dtend </td>
<td>vevent </td>
<td></td>
<td>[[hcalendar|hCalendar]] </td>
<td>Ending date of the object. </td>
</tr>
<tr>
<td>dtreviewed</td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>Date the review was written, NOT necessarily when the review took place. </td>
</tr>
<tr>
<td>dtstart</td>
<td>vevent </td>
<td></td>
<td>[[hcalendar|hCalendar]] </td>
<td>Starting date of the object. (Not to be confused with bday) </td>
</tr>
<tr>
<td>email </td>
<td>vcard, hreview </td>
<td> type, value</td>
<td>[[hcard|hCard]] </td><td>This object's email address. </td>
</tr>
<tr>
<td>extended-address</td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Extended address for this particular address.</td>
</tr>
<tr>
<td>fn</td>
<td>vcard, hreview </td>
<td></td>
<td>[[hcard|hCard]]</td>
<td>The name of the object. </td>
</tr>
<tr>
<td>geo </td>
<td>vcard</td>
<td>latitude, longitude </td>
<td>[[hcard|hCard]] </td>
<td>Geographical coordinates of the object. </td>
</tr>
<tr>
<td>hreview </td>
<td>*webpage</td>
<td></td>
<td>[[hreview|hReview]]</td>
<td>A review of some object. </td>
</tr>
<tr>
<td>item </td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>The item that the object exists for. For example, a review about Coca-Cola would list "Coca-Cola" as the item. </td>
</tr>
<tr>
<td>key </td>
<td>vcard</td>
<td>type, value </td>
<td>[[hcard|hCard]] </td>
<td>Public key of the object</td>
</tr>
<tr>
<td>label </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Formatting to be used by a delivery address label. </td>
</tr>
<tr>
<td>latitude </td>
<td>geo</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>The latitude coordinates of the object. </td>
</tr>
<tr>
<td>locality </td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Locality for this particular address. </td>
</tr>
<tr>
<td>location</td>
<td>vevent </td>
<td></td>
<td>[[hcalendar|hCalendar]] </td>
<td>Intended venue of object. (Not to be confused with adr) </td>
</tr>
<tr>
<td>logo </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Object's logo. </td>
</tr>
<tr>
<td>longitude</td>
<td>geo</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>The longitude coordinates of the object. </td>
</tr>
<tr>
<td>mailer </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Email software used by the object. </td>
</tr>
<tr>
<td>n </td>
<td>vcard</td>
<td> additional-name, family-name, given-name, honorific-prefix, honorific-suffix, nickname</td>
<td>[[hcard|hCard]] </td><td>The name of the unit </td>
</tr>
<tr>
<td>note </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Supplemental information about the object. </td>
</tr>
<tr>
<td>org </td>
<td>vcard</td>
<td>organization-name, organization-unit</td>
<td>[[hcard|hCard]] </td><td>The organization or company of the object. </td>
</tr>
<tr>
<td>organization-name </td>
<td>org</td>
<td></td>
<td>[[hcard|hCard]] </td><td>The name of the organization or company of the object. </td>
</tr>
<tr>
<td>organization-unit </td>
<td>org</td>
<td></td>
<td>[[hcard|hCard]] </td><td>The unit or department of the object. </td>
</tr>
<tr>
<td>permalink </td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>A link to the object. This link should never become invalid. Used in <a> </td>
</tr>
<tr>
<td>photo </td>
<td>vcard, hreview </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>A photo of the object. Used in <img> </td>
</tr>
<tr>
<td>post-office-box </td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Post office box number of this particular address. </td>
</tr>
<tr>
<td>postal-code</td>
<td>adr, value</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Postal code for this particular address. </td>
</tr>
<tr>
<td>profile</td>
<td>*webpage</td>
<td></td>
<td>XMDP</td>
<td>Contains metadata types and definitions. Used in <dl> </td>
</tr>
<tr>
<td>rating </td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>Rating of 1-5 or 0-10 of the object. </td>
</tr>
<tr>
<td>region</td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Region of this particular address. </td>
</tr>
<tr>
<td>rev </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]]</td>
<td>Specifies revision of the [[hcard|hCard]]. </td>
</tr>
<tr>
<td>reviewer </td>
<td>hreview</td>
<td>vcard</td>
<td>[[hreview|hReview]] </td>
<td>Person that wrote the review of the object. </td>
</tr>
<tr>
<td>role </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Information regarding the role of the object. </td>
</tr>
<tr>
<td>sort-string </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td><td>String used to sort this object in an alphabetical list. </td>
</tr>
<tr>
<td>sound </td>
<td>*any</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Audio reading back another element's content. By default, the "fn". </td>
</tr>
<tr>
<td>street-address </td>
<td>adr, value </td>
<td></td>
<td>[[hcard|hCard]]</td>
<td>Street address of this particular address. </td>
</tr>
<tr>
<td>summary </td>
<td>vevent , hreview </td>
<td></td>
<td>[[hcalendar|hCalendar]] </td>
<td>A short summary or subject for the object. </td>
</tr>
<tr>
<td>tel </td>
<td>vcard</td>
<td> type, value</td>
<td>[[hcard|hCard]] </td>
<td>Telephone number of the object </td>
</tr>
<tr>
<td>title </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Job title or functional position of the object.</td>
</tr>
<tr>
<td>type </td>
<td>adr, email, tel </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Defines a type of the parent element. For instance a type of telephone number such as home or work.. Used in conjunction with "value". </td>
</tr>
<tr>
<td>tz </td>
<td>vcard</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>The timezone the object is in. </td>
</tr>
<tr>
<td>uid </td>
<td>*any</td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Globally unique identifier associated with the object, or one of the object's properties. </td>
</tr>
<tr>
<td>url </td>
<td>vcard, vevent , hreview </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>A link to the this object's home page or extended profile. Used in <a> </td>
</tr>
<tr>
<td>value </td>
<td>adr, email, tel </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Used in conjunction with "type". The actual value of a particular type. For instance a telephone number of type work such as +1.415.555.1212. </td>
</tr>
<tr>
<td>vcalendar</td>
<td>*webpage</td>
<td>vevent</td>
<td>[[hcalendar|hCalendar]] </td>
<td>A list of calendar events. </td>
</tr>
<tr>
<td>vcard </td>
<td>*webpage, vevent </td>
<td></td>
<td>[[hcard|hCard]] </td>
<td>Indicates that this element and all containing elements are part of the [[hcard|hCard]] microformat. </td>
</tr>
<tr>
<td> vevent </td>
<td>*webpage, vcalendar </td>
<td></td>
<td>[[hcalendar|hCalendar]]</td>
<td>Indicates that this element and all contained elements are part of the [[hcalendar|hCalendar]] format. </td>
</tr>
<tr>
<td>version</td>
<td>hreview</td>
<td></td>
<td>[[hreview|hReview]] </td>
<td>Version of the format used for the object. </td>
</tr>
<tr>
<td>xoxo </td>
<td>*webpage</td>
<td></td>
<td>[[xoxo|XOXO]]</td>
<td>An outline of data. Used in <ul> and <ol>. </td>
</tr>
</table>

hcard-brainstorming

2006-02-02T15:16:03Z

Atamido: /* Implied "FN and N" Optimization (proposal) */ +1 NICKNAME

= hCardBrainstorming =
__TOC__
== Authors ==
* [http://suda.co.uk/ Brian Suda]
* [http://tantek.com/log/ Tantek Çelik], [http://technorati.com Technorati, Inc]

== Examples ==

* See [[hcard-examples]], which provides several illustrative instructive examples, as well as 1:1 hCard examples for each example in [http://www.ietf.org/rfc/rfc2426.txt RFC 2426].

=== Using RFC2806 with hCard ===

[http://www.ietf.org/rfc/rfc2806.txt RFC 2806] defines the telephone scheme "tel:", "fax:" and "modem:" to handle phone communications with URIs in the same way, "mailto:" is defined for email. It's part of the list or registered schemes by IANA : [http://www.iana.org/assignments/uri-schemes Uniform Resource Identifier (URI) SCHEMES]

<pre><nowiki>
tel telephone [RFC2806]
fax fax [RFC2806]
modem modem [RFC2806]
</nowiki></pre>

It is practical to write your tel number like this.

<pre><nowiki>
<a class="tel" href="tel:+1-919-555-7878>+1-919-555-7878</a>
</nowiki></pre>

or even

<pre><nowiki>
<a class="tel" href="tel:+1-919-555-7878>Mr Smith's phone</a>
</nowiki></pre>

You can add support for "tel:" to your desktop and to your browser

* For Gnome, edit ~/.gnome/Gnome and add something to the URL Handlers section. (Dan Connolly uses this to get galeon to launch telnum from [http://dev.w3.org/cvsweb/2001/telagent/ telagent sources] for tel URIs)
* In Mozilla, [http://dizzy.mozdev.org/ Dizzy]
* In Internet Explorer, [http://msdn.microsoft.com/workshop/networking/pluggable/overview/overview.asp Asynchronous Pluggable Protocols]

On the CSS front… You could for example add automagically an icon. I have put the property !important for those who wants to add it to their own stylesheet in their browsers, so they know type of links when browsing.

<pre><nowiki>
a[href^="tel:"]:before {
content: '\260f ' !important;
padding-left: 20px !important; }

a[href^="mailto:"]:before {
content: '\2709 ' !important;
padding-left: 20px !important; }
</nowiki></pre>

== Encoding "modern" attributes ==

Since vCard was first established, various interactive communication technologies and addressing schemes have been widely adopted. Although there aren't specific properties for these technologies / addressing schemes, they can be captured as URLs or email addresses.

This has now been written up for the most part. See:

http://microformats.org/wiki/hcard-examples#New_Types_of_Contact_Info

Still to be addressed:

* iChat mac.com addresses, simply store "@mac.com" email addresses, e.g.
** <code><a class="email" href="mailto:steve@mac.com">...</code>
* MSN Instant Messenger, you can simple store "@hotmail.com" or "@msn.com" or "@passport.com" email addresses.
* Internet Relay Chat (IRC), use "irc:" URLs.

== Encoding Company data as a Business Card (proposal) ==
In the wild there are several hCards that do not currently validate because they are businesses that have omitted the "fn" property in favor of the "org" property.

Proposal: hCards representing a business or organization MUST set fn AND org to the same value. Parsers may then use this equivalence, if detected, to treat an hCard as the contact info for a business or organization rather than an individual.

Note that [http://microformats.org/wiki/vcard-implementations#organization_vs._individual Apple Address Book supports this semantic when importing vCards].

See the [http://technorati.com/about/contact.html Technorati Contact Info] for an example.

== Implied "FN and N" Optimization (proposal) ==

Right now a parser first looks for an "n" element.

And then if no "n" is present, look for an "fn" element to use to imply an "n" element per the "implied n property" rules in the spec.

BACKGROUND:

Due to the prevalence of the use of "nicknames" or "handles" on the Web, in actual content published on the Web (e.g. authors of reviews), there has been a discussion about adding a "fn" shortcut to the "n" shortcut that used the "nickname" as a fallback.

PROPOSAL:

We should consider adding one more implied optimization after the steps documented above and that is:

If no "fn" is present either, then look for a "nickname" element to use to imply both the "fn", and the "n/given-name", leaving the "n/family-name" as empty.

This would enable "nickname" only hCards for denoting and individual on a website, which is quite common on blogs and reviews published on the Web.
* +1 [[User:Atamido|Atamido]]

== CSS Styles ==
Not only can you create semantics with the hCard values, but you can add CSS styles to them as well. You are free to style the terms in any way you want, but here we can list a few ideas for how to style terms.

If you want to encode hCard data, but do NOT want to display it in the HTML code, then you can hide that tag in CSS with the following code:
<pre><nowiki>
<span style="display: none">Hidden Data</span>
</nowiki></pre>
Transforming applications will still find the data and use it when converting hCards to vCards.

== Auto-Discovery ==
There is currently a debate over the best way to add an auto discovery link to your HTML to extract the vCard.

On the page with the hCard encoding, the best link would be as follows:
<code><nowiki> <link rel="alternate" type="text/vcard" href="..." /> </nowiki></code>
this HTML page is an alternate view of the vCard.

[[User:EtanWexler|EtanWexler]] disagrees with the value of the “type” attribute. The [http://www.iana.org/ Internet Assigned Numbers Authority] has no registration for a “text/vcard” type. The [http://www.iana.org/assignments/media-types/text/ registered and appropriate type] for vCard entities is “text/directory”, as defined in Internet RFC 2425, “[http://www.rfc-editor.org/rfc/rfc2425.txt A MIME Content-Type for Directory Information]”. RFC 2426, “[http://www.rfc-editor.org/rfc/rfc2425.txt vCard MIME Directory Profile]”, specifies the vCard profile for “text/directory” entities, which profile the MIME/HTTP header field “Content-Type” would indicate with a “profile” parameter whose value is “VCARD”. It is unclear whether the HTML/XHTML “type” attribute allows values with parameters. On 2004-05-23, [http://bjoern.hoehrmann.de/ Björn Höhrmann] sent to the [http://www.w3.org/2002/05/html/charter HTML Working Group] a [http://www.w3.org/mid/40ccdc4d.97400945@smtp.bjoern.hoehrmann.de request for clarification] on the issue.

When on a different page, referencing that encoded page in the href would ''not'' be an alternate view of the current page. So a different rel type must be established to decribe that relationship. The ideas vary from specific to vague. The list and categories follow:
<pre><nowiki>
rel="contactinfo"
rel="profile"
rel="author"
rel='PIM'
rel='person'
rel='about'
rel='contact'
rel='hcard'
rel='microformat'
</nowiki></pre>
Example of mixing two rel types to a single page.
rel="hcard xfn"

Note: using rel="vcard" indicates a link directly to a vCard. If the document links to an hCard instead, the indication is untrue and inappropriate.

=== Auto-Discovery for XFN ===

An author will typically their XFN information on a specific page, rather than all pages. In particular, a specific page separate from the home page of their blog, and thus it would be useful to have an explicit rel value to assist in auto-discovery of XFN information.

This was suggested by Jens Alfke on 20050606 at the WWDC blogger's dinner.

== Issues with vCard Applications ==
The following are major vCard application and a description of the features they support and don't support.

=== Apple Address Book ===
* There are issues with importing UTF-8 vCards
* LOGO property is not supported
* only ONE URL is supported
* PHOTO property can only be encoded, no URL references allowed
* SOURCE property is not supported

=== Windows Address Book ===
(not yest tested)

=== Mozilla Thunderbird ===
(not yest tested)

=== Other? ===
(not yest tested)

== Open Questions ==

Q: since many of the components would be using CSS classes for encoding data, it is possible to MIX two different profiles. (e.g. hCard and XFN) There are no real constraints on where/how to enforce class names, these are based on the html profile, since it is difficult to associate the text within the attribute to a specific profile.

<pre><nowiki>
...
<a href="mailto:joe.smith@example.com" class="fn" rel="met">Joe Smith</a>
...
</nowiki></pre>

-- [http://suda.co.uk/ Brian Suda]

Q: Preserving White space? Should the transforming applications preserve extra white space characters? For example:
<pre><nowiki>
<a href="http://mywebsite.com/" class="fn n">
<span class="given-name">John</span>
<span class="other-names">Q.</span>
<span class="family-name">Public</span>
</a>
</nowiki></pre>

When transformed into a vCard, the N property will pick apart the span tags and create the value for N correctly seperated by colons. The FN property will take a string and simply display it. There are two possible renderings for FN:
<pre><nowiki>
John Q. Public

John
Q.
Public
</nowiki></pre>

Either the white-space is preserved or it is not. Which should the transforming applications render?

-- [http://suda.co.uk/ Brian Suda]

A: The parsing application should follow the white space collapsing rules of the mime type it retrieves. I.e. if it retrieves a "text/html" document, it should do HTML white space collapsing.

-- [http://tantek.com/log/ Tantek]

Many of the Questions and Answers are relevant to both ["hCal"] and hCard.

Q: Would it be appropriate to wrap the name of the vCard owner with <dfn/>? This may give the hCard some added semantic value in the XHTML document.
<pre><nowiki>
<span class="agent">
<span class="vcard">
<span class="email">
<a class="internet" href="mailto:jfriday@host.com">
<dfn>
<span class="fn">Joe Friday</span>
</dfn>
</a>
</span>
<span class="tel">+1-919-555-7878</span>
<span class="title">Area Administrator, Assistant</span>
</span>
</span>
</nowiki></pre>
-- [http://www.ben-ward.co.uk/ Ben Ward]

== Applications ==
Applications that are hCard aware or can convert hCard to vCard formats.

=== Copy hCards favelet(s) ===
* I think a Favelet would work nicely here. When you find a page that is hCard friendly, you click the favlet and you get yourself a vCard. This is done! See X2V in the implementations section of the [[hcard|hCard]] spec.

=== Distributed Commentor Icons ===

* See [http://thedredge.org/2005/06/using-hcards-in-your-blog/ using hCards in your blog] for an example of hCards used for comment authors (commentors). The system used there, "Gravatars", is a centralized site that serves commentor icons that requires login etc.

What if we gave each commentor the option of hosting their own icon?

A distributed commentor icon implementation could work like this:

# Given the URL of a commentor, look for an <code><address></code> element with classname of "vcard" at the commentor's URL. The <code><address></code> element is supposed to be the contact information for the page (see [[hcard-faq|hCard FAQ]] for more info), so this makes sense.
# Next, look for the first element inside that hcard that has a classname of "logo".
# Hopefully that element is an <code><img></code>, and if so, use its src to get the commentor's icon.
# Presto. You've got distributed commentor icons!

== Spam prevention ==
hCard uses <code>mailto:</code> links, and therefore
it automatically "inherits" the disadvantage of <code>mailto:</code> links:
These links can be easily detected by emails spiders (used by spammers).

There are ways to prevent email address detection by simple email spiders, while
still retaining full compatibility with (X)HTML applications.
One common way is to "encode" the the "m" of "mail" and "@" with character entities:

Example of the original link:
<pre><nowiki>
<a class="email" href="mailto:john.smith@example.com">john.smith@example.com</a>
</nowiki></pre>

Example of the "encoded" link:
<pre><nowiki>
<a class="e&#109;ail" href="&#109;ailto:john.smith&#064;example.com">john.smith&#064;example.com</a>
</nowiki></pre>

Simple email spiders which do not do character entity decoding will therefore not be able to find your email address.

''Note:'' Perhaps there are or will be email spiders which can decode entities, so the this technique will only help with some (cheap) email spiders.
(See also: http://rbach.priv.at/Misc/2005/EmailSpiderTest)

== Tutorials ==
* How to hCard encode entries in Popular blog software.
* Good reasons to publish your hCard
** as a business, get people to put you in their address book so they'll find you later
** as a business with an email list, get people to add you (with email address) to their address book so that your email list works via whitelisting via the address book.

== Parsing ==
See separate [[hcard-parsing|hCard parsing]] page.

== TODO ==

* The [[hcard-profile]] needs verification and perhaps a URL for retrieving the actual XMDP, rather than as <pre> text on a wiki page.
* Complete translating the examples from the vCard spec into hCard, and place them on a separate hCard examples page.
* Create a "rich" but realistic hCard example, say for example for a salesperson, who wants to put a whole bunch of contact information on their website in order to be found/contacted easily.
* Provide examples of how to encode instant messaging (IM) accounts. Figure out what would the mailto: or aim: URL in hCard look like in vCard. And take a look at what vCard applications do today with IM addresses.

== References ==
=== Normative References ===
* [http://www.ietf.org/rfc/rfc2426.txt RFC 2426] vCard RFC
* [http://www.ietf.org/rfc/rfc2397 RFC 2397] data URI RFC
* [http://gmpg.org/xmdp/ XMDP]
=== Informative References ===
* [http://www.imc.org/pdi/ Personal Data Interchange (PDI) at the Internet Mail Consortium]
* [http://tantek.com/log/2004/07.html#d27t1049 Markup language design notes]
* [http://tantek.com/log/2002/12.html#L20021216t2238 A Touch of Class]

== Other Implementations/Ideas ==
* [http://www.w3.org/TR/2001/NOTE-vcard-rdf-20010222/ Representing vCard Objects in RDF/XML] This could allow conversion of vCard data from XHTML to RDF and from RDF to XHTML
* It would also be possible to convert XFN and hCard to FoaF and back.

== Rejected Suggestions ==

Suggestion: ''The use of class="url" on an <a> tag to represent an hCard URL property is redundant. By virtue of the <a> tag you know this is a URL.''

Rejected. This is a bad suggestion because although it appears to reduce redunancy and keep things cleaner, it also creates a few problems. Without explicitly noting that this is a URL then any <a> tags within a 'vcard' would be considered a URL, for example:
<pre><nowiki>
<span class="vcard">
...
<ul class="categories">
<li><a href="http://w3c.org">W3C</a></li>
</ul>
...
</span>
</nowiki></pre>

There is no way to "turn-off" the encoding of the W3C URL, whereas if "url" needed to be explicitly listed in the class attribute list, then by NOT listing it you could effectively turn it off.

User:Atamido

2006-01-13T17:11:09Z

Atamido:

Name:
Paul Bryson

Location:
Austin, Texas, USA, Earth, Sol, Milkyway

hatom-issues

2006-01-10T18:59:27Z

Atamido: /* Entry Updated (atom:updated) */

= Discussion Participants =

== Editors ==
* [http://www.blogmatrix.com David Janes]

== Authors ==
* [http://www.blogmatrix.com David Janes]
* [http://www.dannyayers.com Danny Ayers]
* [http://tantek.com/ Tantek Çelik]
* [http://www.opendarwin.org/~drernie Ernest Prabhakar]
* [http://members.optusnet.com.au/benjamincarlyle/benjamin/blog/ Benjamin Carlyle]

= Purpose =
Questions or comments about [[hatom|hAtom]] go here. Please add your name
to the [http://microformats.org/wiki?title=hatom-issues&action=edit&section=4 Contributors] section above.

== Goals for hAtom ==
# to provide a blog-post microformat, based on how people actually produce weblogs
# based on (1), use Atom as it provides the most suitable data model for doing so
# based on (2), to make the format useful anywhere Atom might be used in context to create a syndication feed
# provide a baseline envelope format for similar {title|link|content|summary} web pages

== Anti-Goals for hAtom ==
# <em>Not</em> to tell people how to write blogs or what there blog should look like; hAtom marked up blogs should look and behave <em>identically</em> to what they before hAtom was applied.

= New Nomenclature =

[[User:DavidJanes|David Janes]] added this on 2006.01.03. Since we've decided that correspondence to Atom nomenclature is not going to happen, let's just decide on it here. I tried but probably haven't succeeded in pulling all the info from below up so feel free to add new things. Also feel free to change your vote if you see a consensus happening.

'''How to use this'''. If you like a particular use, place something like '<code>: +1 YourName</code>' following the name. Feel free to make as make negative votes. If you have something compelling to say, add it to the Discussion section that follows. Let's settle this out by, say the 10th of January 2006?

== Feed (atom:feed)==
* <code>class="feed"</code> (Atom consistency)
* <code>class="atom-feed"</code> (Atom consistency with prefix)
* <code>class="hfeed"</code> (h* uF consistency)
: +1 DavidJanes
: +1 Tantek
: +1 BenjaminCarlyle
: +1 MarkRickerby

=== Discussion ===

The feed is a root class name of hAtom, similar to "vcalendar" in [[hcalendar|hCalendar]], thus it should be fairly unique, per the root class name [[naming-principles]]. - Tantek

== Entry (atom:entry) ==
* <code>class="entry</code> (Atom consistency)
: +1 MarkRickerby
* <code>class="atom-entry</code> (Atom consistency with prefix)
* <code>class="hentry</code> (h* uF consistency)
: +1 DavidJanes
: +1 Tantek
: +1 BenjaminCarlyle
* <code>class="vjournal</code> (reuse from vCalendar/iCalendar RFC 2445/[[hcalendar|hCalendar]])

=== Discussion ===

Since feed is optional in hAtom (thereby implying the context of the entire XHTML document as the feed), similar to how "vcalendar" is optional in hCalendar (thereby implying a vcalendar context for the entire document), the entry can also be a root class name, similar to "vevent" in [[hcalendar|hCalendar]], thus it should be fairly unique, per the root class name [[naming-principles]].

If we are deliberately rejecting "vjournal", then we may want to exclude the entire "vjournal" object (and any vjournal specific properties) from [[hcalendar|hCalendar]] so that we don't accidentally have two blog post microformats.

Having analyzed the list of vjournal properties and their semantics and compared them with the list of Atom elements and their semantics, I greatly prefer the list and semantics from Atom over vjournal. Thus I would be ok with excluding vjournal from hCalendar, and pointing folks to use hAtom instead, even in the context of an hCalendar element that would otherwise be outputting vjournal entries. To that extent, once hAtom has stabilized, we should develop a mapping between vjournal properties and hAtom properties so that hAtom inside an hCalendar could be converted into BEGIN:VJOURNAL...END:VJOURNAL objects in an iCalendar/ics stream, as well as allowing for the opposite, so that one could even use an iCalendar-compliant authoring tool to create hAtom via the journal feature of said tool.

-Tantek

== Entry Title (atom:title) ==
* <code>class="title"</code> (Atom consistency)
: -1 Tantek. Already defined to mean something else in [[hcard|hCard]]. The same term should not be used to mean different things.
* <code>class="entry-title"</code> (Atom consistency, avoid hCard conflict)
: +½ Paul Bryson, clear=good / hyphenating=bad
* <code>class="heading"</code> (HTML)
* <code>class="subject"</code> (RFC822)
* <code>class="summary"</code> (re-use from and consistency with vCalendar, iCalendar, hCalendar, hReview)
: -1 KevinMarks (clashes with atom)
* <code>class="headline"</code> what they're called in the News/Journalism industry
: +1 Tantek
: +1 KevinMarks
: +1 BenjaminCarlyle, atom:entry/title only
: +½ David Janes, atom:entry/title only
: +½ Paul Bryson, redundant?
* <code>class="fn"</code> (attempt to re-use from [[hcard|hCard]] and [[hreview|hReview]])
: ±0 DavidJanes see my note below
: -1 Tantek (does not mean the "name" of the post/entry)
: +1 BenjaminCarlyle, atom:feed/title only

=== Discussion ===
BenjaminCarlyle: If one were to review a blog entry with hReview we would fill out the "fn" field with the atom:entry/title. This suggests to me that fn may be sufficient for this title usage. headline is more semantically specific, and does seem appropriate. It may be a line-ball call as to whether a new term is required, or whether the atom:entry context is sufficient to indicate the fn is also a headline.

BenjaminCarlyle: Are we considering atom:feed/title in this discussion? There is some suggestion that atom:title should be "fn", separate to any value of atom:entry/title.

DavidJanes: [http://www.ietf.org/rfc/rfc2426.txt vcard] defines "FN" to be "to specify the formatted text corresponding to the name of the object the vCard represents". If we reject FN, are we not making too subtle a distinction that the atom:title isn't the name of the post? I'll also note that the [http://www.ietf.org/rfc/rfc4287 domain experts] believe that the atom:title of an entry is pretty well the same sort of thing as the atom:title of a feed.

First, I have re-evaluated using "fn" for feed:title per the information from Benjamin, David and others. See [http://microformats.org/wiki/blog-post-brainstorming#feed_title this discussion for details].

Second, I now agree with DavidJanes and the domain experts that the title of a feed is very similar (if not nearly identical) in semantics to the title of an entry, neither of which can really be considered a name.

Thus I am -1-ing "fn" for title for entry or feed since it doesn't mean the same thing.

- Tantek

DavidJanes: to summarize (I think), Tantek argues on the link above that atom:title can and does include more than the name.

DavidJanes: we're now at the point where FN is the title of a movie, a DVD, and a book, but not the atom:title of an entry and definitely not the atom:title of a feed.

BenjaminCarlyle: Entry and feed titles are both usually used as the name of the entry of feed, however examples exist where the entry title is [http://planet.freedesktop.org/ changed for republication] or is an auto-generated string (eg [http://www.advogato.org/person/cinamod/ date]). Headline is a good substitute at the entry level, and has a clear analogue in print.

If headline is selected for entry a different term would be required for feed. Headline cannot meaningfully be used for a feed title any more than the name of a newspaper can be called a headline. Working back from the newspaper analogue, I am aware of the use of both name or title to describe the analogous text. In the absence of evidence that a feed's desired title is ever anything but a human-created name for the blog, my support falls behind fn for feed title only. The danger remains that someone will supply non-name data as "fn" in order to "get it into the atom:title element". For this reason I remain open to further naming suggestions and to any example in the wild where this might already occur.

There has been some discussion that because the two are a single term in atom the domain experts consider the semantics to be the same. I suggest differently. The double use of title is inherited from rss, and has always been disambiguated by context. rfc4287 defines title as "a Text construct that conveys a human-readable title for an entry or feed", which conveys no useful semantics. Everything in a microformat is human-readable, and it isn't suprising that the semantics of title are equivalent to "title". To be honest, I would guess that the domain experts didn't give this issue a second thought.

DavidJanes: Let's go with "headline". I'm not in love with it but so it goes. My thinking on this at this point is we won't find a good word that covers atom:entry/title and atom:feed/title and I like the idea of a (somewhat) domain specific word that captures the concept and (especially a big point for me now) it will make mixing hAtom with other uFs a little nicer.

Paul Bryson: I like entry-title for it's clarity. Unfortunately, I also feel that hyphenating names together in a string adds unnecessary complexity. In this case, it also adds a specificity that could be detrimental in the element's reuse. Headline feels redundant with "heading", which is what the element should be. Regardless, this is probably the best of the available choices.

== Entry Content (atom:content) ==
* <code>class="content"</code> (Atom consistency)
: +1 Tantek
: +1 DavidJanes
* <code>class="description"</code> (vCalendar, hCalendar, xFolk, hReview consistency)

=== Discussion ===
It turns out there is actually a very fine semantic distinction between the way "description" is used in vCalendar, hCalendar, xFolk, hReview, and what "content" means. In short, those other microformats are all "about" something else, whether an actual event in spacetime, or another item. Whereas in hAtom is the thing itself. The feed is the data is the item. Thus it makes sense use a different class name than "description". Based on our [[naming-principles]], lacking an existing microformat term for this, we should use a term from a standard. Since Atom uses "content", that is the logical name to bring over and use, whether or not it is "perfect" to capture the semantic we are trying to capture. - Tantek

BenjaminCarlyle: We may also have to consider forms of blogs that carry other media. An <a rel="content" href="..."/> form of content may also have to be considered, although this could still be embedded in a very short html content block. I'm not quite ready to commit to "content" yet, but I agree that description may be a little weak.

== Entry Summary (atom:summary) ==
* <code>class="summary"</code> (re-use from and consistency with Atom)
* <code>class="content-summary"</code> (Atom consistency avoiding hCalendar conflict)
* <code>class="partial-description"</code>
* <code>class="excerpt"</code>
: +1 Tantek
: +1 BenjaminCarlyle
: +1 DavidJanes, my only concern being that they're not always excerpts
* <code>class="abstract"</code>
: +1 KevinMarks

=== Discussion ===
Excerpt is by far the most frequent (>80%) use of summary, thus it makes sense to name it as such. - Tantek

Disagree - Atom allows summary to be distinct from content, though this is less usual. However, by using a class that means summary (eg abstract) we cna convey an excerpt by making it wholly within 'atom:content', or a separate abstract by putting it within the entry but not within 'content' [[User:Kevin Marks|Kevin Marks]]

BenjaminCarlyle: I have been trying to convince meyself that atom:summary differs semantically from iCalendar summary. The "summary or subject" wording from rfc2445 is problematic, and it seems earlier microformats have taken the "subject" side. If we were to start from rfc2445 alone we might go the other way. In the end, though, webster.com defines summary as "covering the main points succinctly". atom:summary is not really consistent with that definition, so I'll swing my weight behind excerpt. On the subject of abstract, I think the semantics are such that "abstract" and "exerpt" are distinct (non-overlapping) sets. webster.com defines abstract as "a summary of points (as of a writing) usually presented in skeletal form". An exerpt is not a summary of points, and a summary of points is not an excerpt. I think tantek is simply suggesting that the 80% win in this case.

Benjamin is correct. The vast majority (easily 80%+) of summaries in Atom, when they exist are excerpts.

In addition:
* WordPress user interface calls it "excerpt"
* MovableType user interface calls it "excerpt"
Thus, based on the principle of user-centered design (an instance of humans first, machines second) as well, in that a user *typing* into the "Excerpt:" field in the UI of their blogging tool, is communicating to the interface that "This is the ''excerpt'' of my blog post", "excerpt" is actually a ''BETTER'' name for this element than summary, or anything else for that matter. Atom should have chosen "excerpt" as well based on this reason alone. - Tantek

== Entry Permalink (atom:link) ==
* <code>rel="bookmark"</code> (HTML consitency)
: +2 DavidJanes
: +1 Tantek
: +1 BenjaminCarlyle
: +1 KevinMarks

=== Discussion ===
BenjaminCarlyle: No real controversy here, unless you want to start giving blog entries or feeds vcards. A vcard could contain entry or feed title as fn, as well as url.

== Entry Published (atom:published) ==
* <code>class="published"</code> (Atom consistency)
: +1 Tantek
: +1 DavidJanes
* <code>class="dtpublished"</code> (Atom consistency with "dt" unofficial pattern)

=== Discussion ===
BenjaminCarlyle: I would still like to see a clear engagement with [[last-modified-brainstorming|last-modified]] before voting on this one.

last-modified reflects the last time the page/file was actually modified, most likely by the user. IMHO it is a 1:1 mapping of the "Date Modified" of a file in a file system. It is a direct mapping of what date is shown for HTTP directory listings.

published is defined in Atom quite differently from that, and among the alternatives it seems best to take the name from Atom precisely. - Tantek

From the [[last-modified-brainstorming]] purpose statement, emphasis added. "To specify the date of publication and the date of modification of a web page (<em>or a part thereof</em>)" - BenjaminCarlyle

Note that Atom chose to drop "created" which is much more reflective of what current file systems etc. support.

The concept of "published" is distinct from a generic "created" notion, in that it indicates when the content was made public or made available to readers (even on intranets) which is often very different than when the author started typing the entry or even first saved the entry.

- Tantek

DavidJanes: It's simple, it's clear, it's not being used it's not being used already. We can make [[last-modified-brainstorming|last-modified]] consistent afterwards

== Entry Updated (atom:updated) ==
* <code>class="updated"</code> (Atom consistency)
: +1 Tantek
: +1 DavidJanes
* <code>class="dtupdated"</code> (Atom consistency with "dt" unofficial pattern)
: +½ Paul Bryson, Not as human readable
* <code>class="last-modified"</code>

=== Discussion ===
Paul Bryson: I would prefer to maintain some consistency with already existing date naming conventions, but acknowledge that these aren't as clearly human readable as they could be.

BenjaminCarlyle: I would still like to see a clear engagement with [[last-modified-brainstorming|last-modified]] before voting on this one.

See discussion for published. Updated is closer to last-modified than published is, however, upon careful reading of the definition of updated in Atom, it is clear that the user has the option of not changing the updated date even if they change the entry, e.g. by fixing a spelling error or something. Thus there is an implied stronger meaning of "this entry has been semantically changed" that is a different enough semantic from last-modified as to justify a new name, and among the alternatives it seems best to take the name from Atom precisely. -Tantek

From [[last-modified-brainstorming]] semantics:
"Since both Atom and HTTP define the last-modified date (or its equivalent) as a "user-defined" value, this microformat should have the same semantics. In other words, the value should represent the last instance that the resource was changed in a way deemed significant to the publisher/author, which is not neccessarily the same as a file-system modified date-time."
- BenjaminCarlyle

They are both user defined values but *different* user defined values.

It is VERY important to note this distinction because Atom chose to note it.

In the 99% case, file-system, web-server (HTTP) context, the last-modified date reflects the last time the *user* modified the file or page, WITHOUT consideration for whether or not the user wanted that change to reflect a change in the last-modified date.

Atom specifically allows for the exception that a user might not update the "updated" date, even when they change the underlying blog post, spelling corrections or whatever.

This is in stark contrast to the traditional application model, where in a word processor, even if you change one character and save, you change the file system last-modified date, and hence the HTTP last-modified headers.

-Tantek

DavidJanes: we can make [[last-modified-brainstorming|last-modified]] consistent afterwards

== Entry Author (atom:author) ==
* <code>class="author"</code> (Atom consistency)
: +1 Tantek

=== Discussion ===
BenjaminCarlyle: I think an author concept is generally useful to microformats, so long as you can make it clear whether it is the author of the uf wrapper or the author of the uf content that is being described. I think any wavering over whether author and contributor are both required is probably a step outside the atom specification. This may be worthwhile, with an xfn-style external definition that could relate a person to a work... or even a rel-tag-based relationship. Can room be left open for both of these possibilities for future expansion, while still providing a clear author -> atom:author translation?

My point is that in practice (>80% case again), contributor is not used. Thus we should exclude it from hAtom in the first version. However, I am ok with ''reserving'' contributor with the intent that if it does somehow take off, we can add it later. -Tantek

== Entry Contributor (atom:contributor) ==
: -1 Tantek
* <code>class="contibutor"</code> (Atom consistency)
: +1 Tantek
: +1 DavidJanes

=== Discussion ===
I recommend we postpone contributor from hAtom first version (thus the -1 before any choices), since the 80% case does not need "contributor". We should reserve the name so we can add it later if we need it (thus the +1 on "contributor"). -Tantek

DavidJanes: deferred

= Questions and Comments =

==Limitations==
There seems to be nothing in the hAtom specification to supply metadata for the blog (title, description, url, feedurl).
There is nothing defined for the encapsulation of comments, comment counts, or links to comment sections.
The microformat would be much more useful with these capabilities added.
-- [[User:Singpolyma|singpolyma]] 03:35, 3 Jan 2006 (PST)

* We've deliberately restricted this to being a "blog post" microformat at this point to make the problem managable. Once the core elements are defined, we will consider extended the spec to cover as much as Atom does. Also note that microformats are compositable, thus, all these things could potentially be defined elsewhere with detrement to this standard. -- DavidJanes
** You brought this microformat to my attention because you disagreed in priciple with the XOXO Blog Format (http://blogxoxo.blogspot.com/2006/01/xoxo-blog-format.html)... yet the only tool that currently works with that format works with comments. note also that at ''least'' comment counts and links to comment sections are part of posts. If you don't want to encapsulate comments I suppose I understand that and can easily create my own format meant to be embedded in yours to facilitate this purpose :) -- [[User:Singpolyma|singpolyma]] 22:13, 3 Jan 2006 (PST)
** Where did I disagree in principle? A: I told you about the existence of hAtom. B: I mentioned several of the design goals for hAtom

In addition, note that frankly we don't care about invisible metadata, because most humans don't care about invisible metadata.

The info about a blog which is *visible* will likely be represented in hAtom if they pass the 80%+ test. To that extent, many blogs have visible title, description, author, and updated information. See [[blog-post-brainstorming]] for more on this. -Tantek

== Nomenclature ==

'''THIS SECTION IS CLOSED. ALL DISCUSSION OF NOMENCLATURE IS NOW MOVED [[hatom-issues#New_Nomenclature|HERE]].'''

Note: microformats [[naming-principles]] include a precise means for coming up with names which should work in the 90% case.

One point to raise for hAtom in particular - we don't simply omit spaces from multiword property names, we use hyphens. E.g. "given-name" and many others in [[hcard|hCard]].

=== Why atomentry? ===
;class="atomentry" (or rather, "atom-entry")
:Why not simply "entry"? The parallel to Atom is clear, but in the
context of a Web page, why add the reference? In case maybe you want
to try for something approaching a string that won't get confused, my
feeling is: forget it. Stick to the local semantics and let the
doc-level (or HTML5 div level?) profile attribute disambiguate. Or to
put it another way, it's premature to see a need at that point.
-- [[DannyAyers]]

* I ([[User:DavidJanes|David Janes]]) chose the "atom" prefix:
** to disambiguate; it is just ''too'' likely that "entry" or "feed" would appear on a random webpage in some other context. My preference would be to have a declarative statement in the XHTML header which would render this argument moot, but at this point the community seems cool on the concept.
** to follow the naming pattern seen in the other "major" microformats ([[hcard|hCard]], [[hcalendar|hCalendar]], etc.)
** because Entrys will not be required to be in Feeds (these rules and the reasons where this can happen will be forthcoming), I choose to disambiguate both
::I don't like the analogy; I think this is more useful than just Atom, so it should be made generic. [[User:DrErnie|Dr. Ernie]] 16:59, 25 Oct 2005 (PDT)

:: [[DannyAyers]] My point exactly, but it wouldn't be the end of the world if the prefix was there - not reallly more than aesthetics...

'''STATUS - RESOLVED'''. We're going with "entry".

:: Tantek: This is actually difficult to consider outside the following issue. In particular, if "entry" is to serve as a potential root class name (similar to "vevent", which may be a root of an [[hcalendar|hCalendar]] event, or may be present in the context of a "vcalendar"), then we should strongly consider "uniquifying" it per our root-class-name practices. Possibilities to consider:
* atom-entry
* hentry
* vjournal (from RFC 2445 and thus borrowed in effect from [[hcalendar|hCalendar]])

=== Why atomfeed? ===
;class="atomfeed" (or rather, "atom-entry")
:As above on the atomprefix. But what does 'feed' mean in the context of a HTML page? Doesn't the <head> element cover the corresponding semantics?
-- [[DannyAyers]]

* It is possible, somewhat common, and [[blog-post-examples#Multiple_EntryGroups_on_a_page|documented]], that multiple feeds can appear on a single page, so it's insufficient to depend on the header, even though this may be the default case. You'll note that I've left out documenting a lot of concepts relating to feeds at a conceptual level, except for noting they exist because I think this is a bit of a swamp that's going to need more thinking
** I'm going to more explicitly recognize that the XHTML document ''may'' act as an implicit feed in many cases
* A Feed is a group of related Entries; what defines the relationship is entirely up to the author of the blog, except to note that if they were to place them together in the same Atom syndication feed, you'd do the same in the XHTML
::This makes sense to me, the way vcalendar is optional since vevent is usually sufficient. [[User:DrErnie|Dr. Ernie]] 16:59, 25 Oct 2005 (PDT)
::Ernie is precisely correct. The vevent/vcalendar :: entry/feed analogy is precisely correct. - Tantek
: The multi-feed point makes sense, but if this data appears on a regular HTML page the question remains, does "feed" make sense? (Maybe just naming aesthetics again) -- [[DannyAyers]]
:: I'm thinking about it more -- I think so, just to split the content of the webpage up (as opposed to blogrolls, headers, footers, etc.) -- [[User:DavidJanes|David Janes]]
:: Agreed with David. Not only does it make sense, it is a bad idea to consider renaming something like that for "aesthetics". - Tantek

'''STATUS - PARTIALLY RESOLVED'''. We're going with "feed" IF and when the Feed element is used. When and where Feed is used at all is still under discussion in the mailing list as of 2005-12-26.

: Tantek: Per the root-class-name naming practices, we should seriously consider a more "unique" name, e.g. some possibilities:
* atom-feed
* hfeed

=== Why rel="link" ? ===
I know this maps through to the atom name, but rel="bookmark" is the established standard for permalinks, and is included in the [http://www.w3.org/TR/html401/types.html#type-links| w3c list of rel's], so there is an Occam's Razor case for using this.
[[KevinMarks]]
* I'd like input from everyone in this -- I'm torn really. Once I knock this thing into more of a complete state, I'll throw this out onto the mailing list for discussion -- [[DavidJanes]]
* Also, "link" is horribly generic and is in fact modified through the "rel" attribute in Atom -- [[DavidJanes]]
* Agreed with what Kevin wrote. Also, rel="link" doesn't actually make sense when you do the analysis as described in the [[rel-faq]]. The destination of the link is not really a "link" itself with respect to the current document/file. - Tantek
* OK, I'm happy with this -- [[User:DavidJanes|David Janes]]

'''STATUS - RESOLVED'''. We are using <code>rel="bookmark"</code>.

* Tantek: agreed.

=== title already defined by hCard ===
The title class is defined by [[hcard|hCard]] to mean "job title". Possible alternatives include (Please add to list):

* 'summary', as used by hReview, hCalendar, VJOURNAL
** Though I agree with the reuse, in this context, it may be confusing for those reading/familiar-with the Atom specification. We may want to avoid the use of 'summary' entirely within hAtom. - Tantek
* 'Subject', as used by SMTP email
* 'heading'
* 'entry-title'
* 'headline'
** as this is what they are most like in blogposts [[User:Kevin Marks|Kevin Marks]]

=== summary already defined and used by vCalendar/iCalendar/hCalendar/hReview ===
The summary class is defined by vCalendar, iCalendar, [[hcalendar|hCalendar]], and also [[hreview|hReview]], to mean "summary or title". Possible alternatives include (add to list):

* description, as used by VJOURNAL. It may be possible to interpret description as text longer than summary which is about the entry content. The hierarchy of detail would be summary (atom:title) -> description (atom:summary) -> content (atom:content)
** description is used ambiguously by RSS to mean 'content' or 'summary', and by hReview and hCalendar to mean 'content'. Doing this would recreate that ambiguity needlessly, when Atom distinguishes it clearly. [[User:Kevin Marks|Kevin Marks]] 15:51, 31 Dec 2005 (PST)
** Kevin's right, and not only that, "description" does NOT mean summary in VJOURNAL. "description" means "full description" in vCalendar, iCalendar, [[hcalendar|hCalendar]], and also [[hreview|hReview]]. See below for where to use "description". We must NOT use "description" to mean summary. - Tantek

* Depending on your interpretation, atom:summary could still be summary. Here is another option: subject (atom:title) -> summary (atom:summary) -> content (atom:content).

* atom:summary is described as abstract in

Tantek: We may want to avoid the use of 'summary' entirely within hAtom. Here are some alternatives:
* excerpt - in practice this is what most people provide instead of full text.
** +1 Tantek
* partial-description
* abstract - Rarely do bloggers actually provide abstracts different from the full text of their posts - this is so NOT the 80% (and thus should be rejected for microformat consideration), but see [http://microformats.org/wiki/blog-post-examples#Entry_contains_summary_content_only blog-post-examples] for some examples.
* content-summary

=== Why content? ===
The concept behind atom:content has precedent in earlier microformats derived from the iCalendar standard as "description".

=== Date and time names alternatives ===
* atom:updated
** VJOURNAL LAST-MODIFIED
*** (also used by HTTP -[[User:RobertBachmann|Robert Bachmann]])
** dtstamp
** dtupdated
* atom:published
** VJOURNAL CREATED
** dtpublished

=== Relationship to hReview definitions needs clarification ===
hAtom will define terminology for the general act of publication that overlaps with hReview's terminology for the specific act of publishing a review of something. The following terms could be pushed back into hReview:

* atom:published -> hReview dtreviewed
* atom:author -> hReview reviewer

"Pushed back" is the wrong direction here.

The right direction is "re-use" by new proposals/drafts. If you see anything in hReview that appears to overlap this new specification, the first thing to do is to see if you can reuse those terms from hReview in this new specification, not vice versa.

In addition, "published" does not mean the same as "dtreviewed" (you might write a restaurant review just after you eat there, but not actually "publish" it until later). "reviewer" is also a more precise semantic than "author", thus the two should not be collapsed.

- Tantek

== hCards ==

Should hCards be required for the <code><address></code> of the Entry Poster? MAY, MUST, SHOULD? Your thoughts please -- [[DavidJanes]]

* [[User:RobertBachmann|Robert Bachmann]]: “MUST” or at least “SHOULD” because atom:author is specified as “The "atom:author" element is a Person construct that indicates the author of the entry or feed.” and <code><address></code>’s semantics are too loose to describe [http://atompub.org/2005/08/17/draft-ietf-atompub-format-11.html#rfc.section.3.2 an Atom person construct] but using <code><addr class="vcard"></code> we would have pretty good 1:1 mappings:
** atom:name ↔ hCard’s FN
** atom:email ↔ hCard’s EMAIL
** atom:uri ↔ hCard’s URI

'''STATUS - OPEN'''. "MAY" is the answer.

Tantek: I think this should be MUST. Atom should have referenced vCard for these semantics and made the mistake of making up their own terms. Let's undo that mistake with hAtom. Also, [[hreview|hReview]] 0.3 is going to make hCard a MUST for the "reviewer" property, based on experience and [[hreview-feedback|feedback]]. Thus we may want to just follow suit with hAtom as well.

DavidJanes: I had based the behavior on hReview 0.2. The problem is getting meaningful information into the blog templates and also I would appeal to parsimony, that is:

<pre><nowiki>
<div class="author">bonehead</div>
</nowiki></pre>

has an assumed defined mapping to

<pre><nowiki>
<div class="author vcard"><span class="fn">bonehead</div></div>
</nowiki></pre>

Since in many cases we're not going to get much more information than that, why add the verbosity? I note an analogous situation in hCard, where N.* are not required because they can be inferred algorithmicly.

== Comparisons ==

This seems precisely analogous to [http://www.meyerweb.com/eric/tools/s5/xoxo-structure-ref.html S5]:
* atomentry <-> slide
* content <-> slidecontent
* summary <-> handout
I'm all for NOT boiling the ocean, but these really seem like the same cup of tea.

-- [[Ernie Prabhakar]]

* See the [[#Purpose]] section above. Basically that drove the design decision for the naming [[User:DavidJanes|David Janes]]

'''STATUS - RESOLVED'''. We're sticking with atom terminology (entry, content, summary).

See above as David says. The atom terminology is both problematic, and doesn't make sufficient reuse of existing microformat terminology. As far as the analogy to S5, yes, there is an analogy, but that doesn't make them the same. The semantics that are represented are different enough to let these evolve independently and see if content authors want them to converge or not. Note that you can overlay hAtom and S5 in the same markup. Anyone that is serious about converging these should *try* using both at the same time in a *real* slide presentation example and report back their experience. - Tantek

== Repeated Elements ==
We allow certain elements to be repeated, such as Entry Permalink, Entry Published and Entry Title, even though there can be at most one real value. We provide "disambiguation" rules for sorting out which is the real value. See [[hatom#Nesting_Rules|here]], [[hatom#Entry_Title|here]], [[hatom#Entry_Permalink|here]] and [[hatom#Entry_Published|here]].

Your thoughts please... -- [[User:DavidJanes|David Janes]]

'''STATUS - RESOLVED'''. The spec has explicit rules for disambiguating all these items if they appear multiple times.

== Opaqueness ==
If you have concerns about [[hatom#hAtom_Opaque|opaqueness]], that is, stopping interpretation below certain hAtom elements, raise them here.

=== Opaqueness of other microformat elements ===
How would we handle a case where someone wanted to provide a vcard under the class=entry element for an individual who was neither author or contributor? Consider the hypothetical case where someone wanted to list their "muse" alongside article author and contributors. If this vcard included a title it might be included accidentally as an <atom:title>.

To summarise,
Is it possible that other microformats found under the class=entry or class=feed elements need to be considered opaque?

-- BenjaminCarlyle

* The issue of "muse" and such is somewhat out of scope. However, I grasp your larger point -- what if we wanted to extend or compositie hAtom in the future. Given the 80-20 rule right now, my feeling is to set aside the problem and if it arises, define a <code>class="opaque"</code> element. -- [[User:DavidJanes|David Janes]]

See the [[mfo-examples]] document, and add further thoughts on this matter there. -- Tantek

=== Opaqueness of summary and content ===
What one publisher considers the entry content may differ from another publisher's point of view. Is the content simply a div that does not contain any author/updated/published metadata etc, or could some of that metadata be relevant to the content as well as the entry? Consider updated. last-modified-brainstorming introduces an idea of using <code><ins></code> and <code><del></code> elements to indicate update time. Updates are also often included in entry content with further information. This suggests to me that the line of opaqueness is blurry.

Perhaps content and summary should not be opaque, and instead rely on the mfo proposal to avoid parsing into microformats below the content level. This approach would allow a single div to contain both "entry" and "content" classes should all metadata be considered content by the author, or would permit any other subset of the metadata to be considered content without repeating one's self.

Consider also the "read more"-style blog. The following nesting of div elements is illegal under current opacity rules:
<code><div class="content"><div class="summary">...</div>...</div></code>

A further example is provided by _fil_ on #microformats, who uses the rel-tag microformat within his atom:content to be handled as tags in his feed reader.

== Identification ==
The current spec under Schema:Nomenclature:Entry includes the text:
"if practical, also define id="unique-identifier" to the Entry"
What should be done with this id by parsers? How does this interact (if at all) with the interpretation of a rel=bookmark within the entry?

Also, how should a feed <id> element be filled out from a hAtom source document? Is a rel=bookmark at the feed level required?

The id elements in atom are supposed to survive all future movements of the blog t new hosting arragements and the like. Are current feed URLs or even rel=bookmarks solid enough?

'''STATUS - OPEN'''.

== HTML Title ==
Atom permits title to be either plain text or html. hAtom2Atom.xsl currently uses a plain text translation, and some feed readers seem not to handle html titles well (liferea does not normalize-whitespace, for example). Should a hAtom title element become a plain text or a html atom title? If so, should a subset of html be passed through rather than all html (including id, etc)?

== rel-tag ==
Should hAtom use rel-tag for atom category elements?

IMHO yes. -- Tantek

A version of this is currently implemented in hAtom2Atom.xsl, but the interpretation of rel-tag is not straightforward.

rel-tag uses the last path segment of a URI as its tag, for example <code><a href="http://apple.com/ipod" rel="tag">iPod</a></code>. Human-friendly content is permitted within the anchor. Atom defines three attributes on a category element. "term" is the category in use. "scheme" is a namespace for this category. "label" is a human-friendly text-only version of the category.

* This looks like a clear mapping to me - term is last path segment; scheme is the tagspace and label is the text within the anchor? The problem is if the scheme + tag is not a true URL but a URI. So for your example, term is 'ipod, scheme is 'http://apple.com/' and label is iPod. [[User:Kevin Marks|Kevin Marks]] 15:03, 31 Dec 2005 (PST)

hAtom2Atom.xsl does not currently supply a scheme. Label is taken from the content of the anchor tag, and no special handling for content such as the title attribute of an img element is performed. Term is the portion of the href after the last slash character.

rel-tag permits url encoding for IRIs, as well as conversion of spaces to plus (+) characters. It is unclear whether the conversion of rel-tag data to atom:category/@term should attempt to reverse any such encoding. The handling of plus characters may be especially difficult to reverse (are the plus characters, or spaces?).

* They are spaces. If you want plus characters use %2B Perhaps I should add this to rel-tag. [[User:Kevin Marks|Kevin Marks]] 15:03, 31 Dec 2005 (PST)

== Excess disambiguation rules? ==
Disambiguation rules apply to feed and entry title, and hAtom2Atom.xsl implements these. Rules also apply to permalink, published, and updated. These are currently not implemented. If they appear multiple times in the source document they are repeated multiple times.

It is clear that the data relating to these fields may be repeated within a hAtom entry, however the class notation may not. Only one element need be marked with rel="bookmark". Only one need be marked published, and one updated. Should the disambiguation rules be removed and only one element be allowed for each value, or is there value to the publisher in marking different elements with the hAtom class names?

== Dependancies ==
=== mfo ===
Does this specification depend on acceptance of a hAtom-compatible mfo?
See [[mfo-examples]].

=== last-modified ===
Does this specification depend on acceptance of a hAtom-compatible last-modified?

== Is atom:content necessary? ==
Atom's structure is built up around separating content and other metadata. atom:updated, atom:author, and the like are separate from atom:content any may contain repeated data. Microformats are built around bringing the content and the metadata back together. Is there are genuine use case for identifying only part of the atom entry as content? Presumably the whole html entry is fit for human consumption, or it wouldn't be part of a microformatted web page. Could that whole html snippet be used as the content?

== Published as default value for atom:updated ==
It seems to be common practice to include an "updated" section within the main blog content to track updates to an atom:entry as they occur. It is less common to include a value for atom:published within atom:content. atom:published is usually provided by a machine, but atom:updated is often provided by a human.

I suggest that if a value of published exists but no value for updated exists that the required updated field be filled out from the optional published field. I think this would make changing the required value of updated easier for publishers. Also, several updates may occur to a single entry. I suggest that a disambiguation rule be applied such that the the latest timestamp of any updated field be used if several exist. The overal parser semantics would therefore be:
# If multiple updated fields exist, choose the most recent one.
# If only one updated field exists, choose that value.
# If no updated field exists but a published field exists, use the published value for atom:updated.

=See Also=
* [[hatom|hAtom]] - the draft proposal
* [[hatom-issues]] - problems? complaints? ideas? Put them here
* [[hatom-faq]] - knowledge base
* [[blog-post-brainstorming]]
* [[blog-post-formats]]
* [[blog-post-examples]]
* [[blog-description-format]] - how to describe a blog (as opposed to the individual entries, which is what we're doing here)
* [[mfo-examples]]
* [[naming-principles]]

hatom-issues

2006-01-10T18:45:05Z

Atamido: /* Entry Title (atom:title) */

= Discussion Participants =

== Editors ==
* [http://www.blogmatrix.com David Janes]

== Authors ==
* [http://www.blogmatrix.com David Janes]
* [http://www.dannyayers.com Danny Ayers]
* [http://tantek.com/ Tantek Çelik]
* [http://www.opendarwin.org/~drernie Ernest Prabhakar]
* [http://members.optusnet.com.au/benjamincarlyle/benjamin/blog/ Benjamin Carlyle]

= Purpose =
Questions or comments about [[hatom|hAtom]] go here. Please add your name
to the [http://microformats.org/wiki?title=hatom-issues&action=edit&section=4 Contributors] section above.

== Goals for hAtom ==
# to provide a blog-post microformat, based on how people actually produce weblogs
# based on (1), use Atom as it provides the most suitable data model for doing so
# based on (2), to make the format useful anywhere Atom might be used in context to create a syndication feed
# provide a baseline envelope format for similar {title|link|content|summary} web pages

== Anti-Goals for hAtom ==
# <em>Not</em> to tell people how to write blogs or what there blog should look like; hAtom marked up blogs should look and behave <em>identically</em> to what they before hAtom was applied.

= New Nomenclature =

[[User:DavidJanes|David Janes]] added this on 2006.01.03. Since we've decided that correspondence to Atom nomenclature is not going to happen, let's just decide on it here. I tried but probably haven't succeeded in pulling all the info from below up so feel free to add new things. Also feel free to change your vote if you see a consensus happening.

'''How to use this'''. If you like a particular use, place something like '<code>: +1 YourName</code>' following the name. Feel free to make as make negative votes. If you have something compelling to say, add it to the Discussion section that follows. Let's settle this out by, say the 10th of January 2006?

== Feed (atom:feed)==
* <code>class="feed"</code> (Atom consistency)
* <code>class="atom-feed"</code> (Atom consistency with prefix)
* <code>class="hfeed"</code> (h* uF consistency)
: +1 DavidJanes
: +1 Tantek
: +1 BenjaminCarlyle
: +1 MarkRickerby

=== Discussion ===

The feed is a root class name of hAtom, similar to "vcalendar" in [[hcalendar|hCalendar]], thus it should be fairly unique, per the root class name [[naming-principles]]. - Tantek

== Entry (atom:entry) ==
* <code>class="entry</code> (Atom consistency)
: +1 MarkRickerby
* <code>class="atom-entry</code> (Atom consistency with prefix)
* <code>class="hentry</code> (h* uF consistency)
: +1 DavidJanes
: +1 Tantek
: +1 BenjaminCarlyle
* <code>class="vjournal</code> (reuse from vCalendar/iCalendar RFC 2445/[[hcalendar|hCalendar]])

=== Discussion ===

Since feed is optional in hAtom (thereby implying the context of the entire XHTML document as the feed), similar to how "vcalendar" is optional in hCalendar (thereby implying a vcalendar context for the entire document), the entry can also be a root class name, similar to "vevent" in [[hcalendar|hCalendar]], thus it should be fairly unique, per the root class name [[naming-principles]].

If we are deliberately rejecting "vjournal", then we may want to exclude the entire "vjournal" object (and any vjournal specific properties) from [[hcalendar|hCalendar]] so that we don't accidentally have two blog post microformats.

Having analyzed the list of vjournal properties and their semantics and compared them with the list of Atom elements and their semantics, I greatly prefer the list and semantics from Atom over vjournal. Thus I would be ok with excluding vjournal from hCalendar, and pointing folks to use hAtom instead, even in the context of an hCalendar element that would otherwise be outputting vjournal entries. To that extent, once hAtom has stabilized, we should develop a mapping between vjournal properties and hAtom properties so that hAtom inside an hCalendar could be converted into BEGIN:VJOURNAL...END:VJOURNAL objects in an iCalendar/ics stream, as well as allowing for the opposite, so that one could even use an iCalendar-compliant authoring tool to create hAtom via the journal feature of said tool.

-Tantek

== Entry Title (atom:title) ==
* <code>class="title"</code> (Atom consistency)
: -1 Tantek. Already defined to mean something else in [[hcard|hCard]]. The same term should not be used to mean different things.
* <code>class="entry-title"</code> (Atom consistency, avoid hCard conflict)
: +½ Paul Bryson, clear=good / hyphenating=bad
* <code>class="heading"</code> (HTML)
* <code>class="subject"</code> (RFC822)
* <code>class="summary"</code> (re-use from and consistency with vCalendar, iCalendar, hCalendar, hReview)
: -1 KevinMarks (clashes with atom)
* <code>class="headline"</code> what they're called in the News/Journalism industry
: +1 Tantek
: +1 KevinMarks
: +1 BenjaminCarlyle, atom:entry/title only
: +½ David Janes, atom:entry/title only
: +½ Paul Bryson, redundant?
* <code>class="fn"</code> (attempt to re-use from [[hcard|hCard]] and [[hreview|hReview]])
: ±0 DavidJanes see my note below
: -1 Tantek (does not mean the "name" of the post/entry)
: +1 BenjaminCarlyle, atom:feed/title only

=== Discussion ===
BenjaminCarlyle: If one were to review a blog entry with hReview we would fill out the "fn" field with the atom:entry/title. This suggests to me that fn may be sufficient for this title usage. headline is more semantically specific, and does seem appropriate. It may be a line-ball call as to whether a new term is required, or whether the atom:entry context is sufficient to indicate the fn is also a headline.

BenjaminCarlyle: Are we considering atom:feed/title in this discussion? There is some suggestion that atom:title should be "fn", separate to any value of atom:entry/title.

DavidJanes: [http://www.ietf.org/rfc/rfc2426.txt vcard] defines "FN" to be "to specify the formatted text corresponding to the name of the object the vCard represents". If we reject FN, are we not making too subtle a distinction that the atom:title isn't the name of the post? I'll also note that the [http://www.ietf.org/rfc/rfc4287 domain experts] believe that the atom:title of an entry is pretty well the same sort of thing as the atom:title of a feed.

First, I have re-evaluated using "fn" for feed:title per the information from Benjamin, David and others. See [http://microformats.org/wiki/blog-post-brainstorming#feed_title this discussion for details].

Second, I now agree with DavidJanes and the domain experts that the title of a feed is very similar (if not nearly identical) in semantics to the title of an entry, neither of which can really be considered a name.

Thus I am -1-ing "fn" for title for entry or feed since it doesn't mean the same thing.

- Tantek

DavidJanes: to summarize (I think), Tantek argues on the link above that atom:title can and does include more than the name.

DavidJanes: we're now at the point where FN is the title of a movie, a DVD, and a book, but not the atom:title of an entry and definitely not the atom:title of a feed.

BenjaminCarlyle: Entry and feed titles are both usually used as the name of the entry of feed, however examples exist where the entry title is [http://planet.freedesktop.org/ changed for republication] or is an auto-generated string (eg [http://www.advogato.org/person/cinamod/ date]). Headline is a good substitute at the entry level, and has a clear analogue in print.

If headline is selected for entry a different term would be required for feed. Headline cannot meaningfully be used for a feed title any more than the name of a newspaper can be called a headline. Working back from the newspaper analogue, I am aware of the use of both name or title to describe the analogous text. In the absence of evidence that a feed's desired title is ever anything but a human-created name for the blog, my support falls behind fn for feed title only. The danger remains that someone will supply non-name data as "fn" in order to "get it into the atom:title element". For this reason I remain open to further naming suggestions and to any example in the wild where this might already occur.

There has been some discussion that because the two are a single term in atom the domain experts consider the semantics to be the same. I suggest differently. The double use of title is inherited from rss, and has always been disambiguated by context. rfc4287 defines title as "a Text construct that conveys a human-readable title for an entry or feed", which conveys no useful semantics. Everything in a microformat is human-readable, and it isn't suprising that the semantics of title are equivalent to "title". To be honest, I would guess that the domain experts didn't give this issue a second thought.

DavidJanes: Let's go with "headline". I'm not in love with it but so it goes. My thinking on this at this point is we won't find a good word that covers atom:entry/title and atom:feed/title and I like the idea of a (somewhat) domain specific word that captures the concept and (especially a big point for me now) it will make mixing hAtom with other uFs a little nicer.

Paul Bryson: I like entry-title for it's clarity. Unfortunately, I also feel that hyphenating names together in a string adds unnecessary complexity. In this case, it also adds a specificity that could be detrimental in the element's reuse. Headline feels redundant with "heading", which is what the element should be. Regardless, this is probably the best of the available choices.

== Entry Content (atom:content) ==
* <code>class="content"</code> (Atom consistency)
: +1 Tantek
: +1 DavidJanes
* <code>class="description"</code> (vCalendar, hCalendar, xFolk, hReview consistency)

=== Discussion ===
It turns out there is actually a very fine semantic distinction between the way "description" is used in vCalendar, hCalendar, xFolk, hReview, and what "content" means. In short, those other microformats are all "about" something else, whether an actual event in spacetime, or another item. Whereas in hAtom is the thing itself. The feed is the data is the item. Thus it makes sense use a different class name than "description". Based on our [[naming-principles]], lacking an existing microformat term for this, we should use a term from a standard. Since Atom uses "content", that is the logical name to bring over and use, whether or not it is "perfect" to capture the semantic we are trying to capture. - Tantek

BenjaminCarlyle: We may also have to consider forms of blogs that carry other media. An <a rel="content" href="..."/> form of content may also have to be considered, although this could still be embedded in a very short html content block. I'm not quite ready to commit to "content" yet, but I agree that description may be a little weak.

== Entry Summary (atom:summary) ==
* <code>class="summary"</code> (re-use from and consistency with Atom)
* <code>class="content-summary"</code> (Atom consistency avoiding hCalendar conflict)
* <code>class="partial-description"</code>
* <code>class="excerpt"</code>
: +1 Tantek
: +1 BenjaminCarlyle
: +1 DavidJanes, my only concern being that they're not always excerpts
* <code>class="abstract"</code>
: +1 KevinMarks

=== Discussion ===
Excerpt is by far the most frequent (>80%) use of summary, thus it makes sense to name it as such. - Tantek

Disagree - Atom allows summary to be distinct from content, though this is less usual. However, by using a class that means summary (eg abstract) we cna convey an excerpt by making it wholly within 'atom:content', or a separate abstract by putting it within the entry but not within 'content' [[User:Kevin Marks|Kevin Marks]]

BenjaminCarlyle: I have been trying to convince meyself that atom:summary differs semantically from iCalendar summary. The "summary or subject" wording from rfc2445 is problematic, and it seems earlier microformats have taken the "subject" side. If we were to start from rfc2445 alone we might go the other way. In the end, though, webster.com defines summary as "covering the main points succinctly". atom:summary is not really consistent with that definition, so I'll swing my weight behind excerpt. On the subject of abstract, I think the semantics are such that "abstract" and "exerpt" are distinct (non-overlapping) sets. webster.com defines abstract as "a summary of points (as of a writing) usually presented in skeletal form". An exerpt is not a summary of points, and a summary of points is not an excerpt. I think tantek is simply suggesting that the 80% win in this case.

Benjamin is correct. The vast majority (easily 80%+) of summaries in Atom, when they exist are excerpts.

In addition:
* WordPress user interface calls it "excerpt"
* MovableType user interface calls it "excerpt"
Thus, based on the principle of user-centered design (an instance of humans first, machines second) as well, in that a user *typing* into the "Excerpt:" field in the UI of their blogging tool, is communicating to the interface that "This is the ''excerpt'' of my blog post", "excerpt" is actually a ''BETTER'' name for this element than summary, or anything else for that matter. Atom should have chosen "excerpt" as well based on this reason alone. - Tantek

== Entry Permalink (atom:link) ==
* <code>rel="bookmark"</code> (HTML consitency)
: +2 DavidJanes
: +1 Tantek
: +1 BenjaminCarlyle
: +1 KevinMarks

=== Discussion ===
BenjaminCarlyle: No real controversy here, unless you want to start giving blog entries or feeds vcards. A vcard could contain entry or feed title as fn, as well as url.

== Entry Published (atom:published) ==
* <code>class="published"</code> (Atom consistency)
: +1 Tantek
: +1 DavidJanes
* <code>class="dtpublished"</code> (Atom consistency with "dt" unofficial pattern)

=== Discussion ===
BenjaminCarlyle: I would still like to see a clear engagement with [[last-modified-brainstorming|last-modified]] before voting on this one.

last-modified reflects the last time the page/file was actually modified, most likely by the user. IMHO it is a 1:1 mapping of the "Date Modified" of a file in a file system. It is a direct mapping of what date is shown for HTTP directory listings.

published is defined in Atom quite differently from that, and among the alternatives it seems best to take the name from Atom precisely. - Tantek

From the [[last-modified-brainstorming]] purpose statement, emphasis added. "To specify the date of publication and the date of modification of a web page (<em>or a part thereof</em>)" - BenjaminCarlyle

Note that Atom chose to drop "created" which is much more reflective of what current file systems etc. support.

The concept of "published" is distinct from a generic "created" notion, in that it indicates when the content was made public or made available to readers (even on intranets) which is often very different than when the author started typing the entry or even first saved the entry.

- Tantek

DavidJanes: It's simple, it's clear, it's not being used it's not being used already. We can make [[last-modified-brainstorming|last-modified]] consistent afterwards

== Entry Updated (atom:updated) ==
* <code>class="updated"</code> (Atom consistency)
: +1 Tantek
: +1 DavidJanes
* <code>class="dtupdated"</code> (Atom consistency with "dt" unofficial pattern)
* <code>class="last-modified"</code>

=== Discussion ===
BenjaminCarlyle: I would still like to see a clear engagement with [[last-modified-brainstorming|last-modified]] before voting on this one.

See discussion for published. Updated is closer to last-modified than published is, however, upon careful reading of the definition of updated in Atom, it is clear that the user has the option of not changing the updated date even if they change the entry, e.g. by fixing a spelling error or something. Thus there is an implied stronger meaning of "this entry has been semantically changed" that is a different enough semantic from last-modified as to justify a new name, and among the alternatives it seems best to take the name from Atom precisely. -Tantek

From [[last-modified-brainstorming]] semantics:
"Since both Atom and HTTP define the last-modified date (or its equivalent) as a "user-defined" value, this microformat should have the same semantics. In other words, the value should represent the last instance that the resource was changed in a way deemed significant to the publisher/author, which is not neccessarily the same as a file-system modified date-time."
- BenjaminCarlyle

They are both user defined values but *different* user defined values.

It is VERY important to note this distinction because Atom chose to note it.

In the 99% case, file-system, web-server (HTTP) context, the last-modified date reflects the last time the *user* modified the file or page, WITHOUT consideration for whether or not the user wanted that change to reflect a change in the last-modified date.

Atom specifically allows for the exception that a user might not update the "updated" date, even when they change the underlying blog post, spelling corrections or whatever.

This is in stark contrast to the traditional application model, where in a word processor, even if you change one character and save, you change the file system last-modified date, and hence the HTTP last-modified headers.

-Tantek

DavidJanes: we can make [[last-modified-brainstorming|last-modified]] consistent afterwards

== Entry Author (atom:author) ==
* <code>class="author"</code> (Atom consistency)
: +1 Tantek

=== Discussion ===
BenjaminCarlyle: I think an author concept is generally useful to microformats, so long as you can make it clear whether it is the author of the uf wrapper or the author of the uf content that is being described. I think any wavering over whether author and contributor are both required is probably a step outside the atom specification. This may be worthwhile, with an xfn-style external definition that could relate a person to a work... or even a rel-tag-based relationship. Can room be left open for both of these possibilities for future expansion, while still providing a clear author -> atom:author translation?

My point is that in practice (>80% case again), contributor is not used. Thus we should exclude it from hAtom in the first version. However, I am ok with ''reserving'' contributor with the intent that if it does somehow take off, we can add it later. -Tantek

== Entry Contributor (atom:contributor) ==
: -1 Tantek
* <code>class="contibutor"</code> (Atom consistency)
: +1 Tantek
: +1 DavidJanes

=== Discussion ===
I recommend we postpone contributor from hAtom first version (thus the -1 before any choices), since the 80% case does not need "contributor". We should reserve the name so we can add it later if we need it (thus the +1 on "contributor"). -Tantek

DavidJanes: deferred

= Questions and Comments =

==Limitations==
There seems to be nothing in the hAtom specification to supply metadata for the blog (title, description, url, feedurl).
There is nothing defined for the encapsulation of comments, comment counts, or links to comment sections.
The microformat would be much more useful with these capabilities added.
-- [[User:Singpolyma|singpolyma]] 03:35, 3 Jan 2006 (PST)

* We've deliberately restricted this to being a "blog post" microformat at this point to make the problem managable. Once the core elements are defined, we will consider extended the spec to cover as much as Atom does. Also note that microformats are compositable, thus, all these things could potentially be defined elsewhere with detrement to this standard. -- DavidJanes
** You brought this microformat to my attention because you disagreed in priciple with the XOXO Blog Format (http://blogxoxo.blogspot.com/2006/01/xoxo-blog-format.html)... yet the only tool that currently works with that format works with comments. note also that at ''least'' comment counts and links to comment sections are part of posts. If you don't want to encapsulate comments I suppose I understand that and can easily create my own format meant to be embedded in yours to facilitate this purpose :) -- [[User:Singpolyma|singpolyma]] 22:13, 3 Jan 2006 (PST)
** Where did I disagree in principle? A: I told you about the existence of hAtom. B: I mentioned several of the design goals for hAtom

In addition, note that frankly we don't care about invisible metadata, because most humans don't care about invisible metadata.

The info about a blog which is *visible* will likely be represented in hAtom if they pass the 80%+ test. To that extent, many blogs have visible title, description, author, and updated information. See [[blog-post-brainstorming]] for more on this. -Tantek

== Nomenclature ==

'''THIS SECTION IS CLOSED. ALL DISCUSSION OF NOMENCLATURE IS NOW MOVED [[hatom-issues#New_Nomenclature|HERE]].'''

Note: microformats [[naming-principles]] include a precise means for coming up with names which should work in the 90% case.

One point to raise for hAtom in particular - we don't simply omit spaces from multiword property names, we use hyphens. E.g. "given-name" and many others in [[hcard|hCard]].

=== Why atomentry? ===
;class="atomentry" (or rather, "atom-entry")
:Why not simply "entry"? The parallel to Atom is clear, but in the
context of a Web page, why add the reference? In case maybe you want
to try for something approaching a string that won't get confused, my
feeling is: forget it. Stick to the local semantics and let the
doc-level (or HTML5 div level?) profile attribute disambiguate. Or to
put it another way, it's premature to see a need at that point.
-- [[DannyAyers]]

* I ([[User:DavidJanes|David Janes]]) chose the "atom" prefix:
** to disambiguate; it is just ''too'' likely that "entry" or "feed" would appear on a random webpage in some other context. My preference would be to have a declarative statement in the XHTML header which would render this argument moot, but at this point the community seems cool on the concept.
** to follow the naming pattern seen in the other "major" microformats ([[hcard|hCard]], [[hcalendar|hCalendar]], etc.)
** because Entrys will not be required to be in Feeds (these rules and the reasons where this can happen will be forthcoming), I choose to disambiguate both
::I don't like the analogy; I think this is more useful than just Atom, so it should be made generic. [[User:DrErnie|Dr. Ernie]] 16:59, 25 Oct 2005 (PDT)

:: [[DannyAyers]] My point exactly, but it wouldn't be the end of the world if the prefix was there - not reallly more than aesthetics...

'''STATUS - RESOLVED'''. We're going with "entry".

:: Tantek: This is actually difficult to consider outside the following issue. In particular, if "entry" is to serve as a potential root class name (similar to "vevent", which may be a root of an [[hcalendar|hCalendar]] event, or may be present in the context of a "vcalendar"), then we should strongly consider "uniquifying" it per our root-class-name practices. Possibilities to consider:
* atom-entry
* hentry
* vjournal (from RFC 2445 and thus borrowed in effect from [[hcalendar|hCalendar]])

=== Why atomfeed? ===
;class="atomfeed" (or rather, "atom-entry")
:As above on the atomprefix. But what does 'feed' mean in the context of a HTML page? Doesn't the <head> element cover the corresponding semantics?
-- [[DannyAyers]]

* It is possible, somewhat common, and [[blog-post-examples#Multiple_EntryGroups_on_a_page|documented]], that multiple feeds can appear on a single page, so it's insufficient to depend on the header, even though this may be the default case. You'll note that I've left out documenting a lot of concepts relating to feeds at a conceptual level, except for noting they exist because I think this is a bit of a swamp that's going to need more thinking
** I'm going to more explicitly recognize that the XHTML document ''may'' act as an implicit feed in many cases
* A Feed is a group of related Entries; what defines the relationship is entirely up to the author of the blog, except to note that if they were to place them together in the same Atom syndication feed, you'd do the same in the XHTML
::This makes sense to me, the way vcalendar is optional since vevent is usually sufficient. [[User:DrErnie|Dr. Ernie]] 16:59, 25 Oct 2005 (PDT)
::Ernie is precisely correct. The vevent/vcalendar :: entry/feed analogy is precisely correct. - Tantek
: The multi-feed point makes sense, but if this data appears on a regular HTML page the question remains, does "feed" make sense? (Maybe just naming aesthetics again) -- [[DannyAyers]]
:: I'm thinking about it more -- I think so, just to split the content of the webpage up (as opposed to blogrolls, headers, footers, etc.) -- [[User:DavidJanes|David Janes]]
:: Agreed with David. Not only does it make sense, it is a bad idea to consider renaming something like that for "aesthetics". - Tantek

'''STATUS - PARTIALLY RESOLVED'''. We're going with "feed" IF and when the Feed element is used. When and where Feed is used at all is still under discussion in the mailing list as of 2005-12-26.

: Tantek: Per the root-class-name naming practices, we should seriously consider a more "unique" name, e.g. some possibilities:
* atom-feed
* hfeed

=== Why rel="link" ? ===
I know this maps through to the atom name, but rel="bookmark" is the established standard for permalinks, and is included in the [http://www.w3.org/TR/html401/types.html#type-links| w3c list of rel's], so there is an Occam's Razor case for using this.
[[KevinMarks]]
* I'd like input from everyone in this -- I'm torn really. Once I knock this thing into more of a complete state, I'll throw this out onto the mailing list for discussion -- [[DavidJanes]]
* Also, "link" is horribly generic and is in fact modified through the "rel" attribute in Atom -- [[DavidJanes]]
* Agreed with what Kevin wrote. Also, rel="link" doesn't actually make sense when you do the analysis as described in the [[rel-faq]]. The destination of the link is not really a "link" itself with respect to the current document/file. - Tantek
* OK, I'm happy with this -- [[User:DavidJanes|David Janes]]

'''STATUS - RESOLVED'''. We are using <code>rel="bookmark"</code>.

* Tantek: agreed.

=== title already defined by hCard ===
The title class is defined by [[hcard|hCard]] to mean "job title". Possible alternatives include (Please add to list):

* 'summary', as used by hReview, hCalendar, VJOURNAL
** Though I agree with the reuse, in this context, it may be confusing for those reading/familiar-with the Atom specification. We may want to avoid the use of 'summary' entirely within hAtom. - Tantek
* 'Subject', as used by SMTP email
* 'heading'
* 'entry-title'
* 'headline'
** as this is what they are most like in blogposts [[User:Kevin Marks|Kevin Marks]]

=== summary already defined and used by vCalendar/iCalendar/hCalendar/hReview ===
The summary class is defined by vCalendar, iCalendar, [[hcalendar|hCalendar]], and also [[hreview|hReview]], to mean "summary or title". Possible alternatives include (add to list):

* description, as used by VJOURNAL. It may be possible to interpret description as text longer than summary which is about the entry content. The hierarchy of detail would be summary (atom:title) -> description (atom:summary) -> content (atom:content)
** description is used ambiguously by RSS to mean 'content' or 'summary', and by hReview and hCalendar to mean 'content'. Doing this would recreate that ambiguity needlessly, when Atom distinguishes it clearly. [[User:Kevin Marks|Kevin Marks]] 15:51, 31 Dec 2005 (PST)
** Kevin's right, and not only that, "description" does NOT mean summary in VJOURNAL. "description" means "full description" in vCalendar, iCalendar, [[hcalendar|hCalendar]], and also [[hreview|hReview]]. See below for where to use "description". We must NOT use "description" to mean summary. - Tantek

* Depending on your interpretation, atom:summary could still be summary. Here is another option: subject (atom:title) -> summary (atom:summary) -> content (atom:content).

* atom:summary is described as abstract in

Tantek: We may want to avoid the use of 'summary' entirely within hAtom. Here are some alternatives:
* excerpt - in practice this is what most people provide instead of full text.
** +1 Tantek
* partial-description
* abstract - Rarely do bloggers actually provide abstracts different from the full text of their posts - this is so NOT the 80% (and thus should be rejected for microformat consideration), but see [http://microformats.org/wiki/blog-post-examples#Entry_contains_summary_content_only blog-post-examples] for some examples.
* content-summary

=== Why content? ===
The concept behind atom:content has precedent in earlier microformats derived from the iCalendar standard as "description".

=== Date and time names alternatives ===
* atom:updated
** VJOURNAL LAST-MODIFIED
*** (also used by HTTP -[[User:RobertBachmann|Robert Bachmann]])
** dtstamp
** dtupdated
* atom:published
** VJOURNAL CREATED
** dtpublished

=== Relationship to hReview definitions needs clarification ===
hAtom will define terminology for the general act of publication that overlaps with hReview's terminology for the specific act of publishing a review of something. The following terms could be pushed back into hReview:

* atom:published -> hReview dtreviewed
* atom:author -> hReview reviewer

"Pushed back" is the wrong direction here.

The right direction is "re-use" by new proposals/drafts. If you see anything in hReview that appears to overlap this new specification, the first thing to do is to see if you can reuse those terms from hReview in this new specification, not vice versa.

In addition, "published" does not mean the same as "dtreviewed" (you might write a restaurant review just after you eat there, but not actually "publish" it until later). "reviewer" is also a more precise semantic than "author", thus the two should not be collapsed.

- Tantek

== hCards ==

Should hCards be required for the <code><address></code> of the Entry Poster? MAY, MUST, SHOULD? Your thoughts please -- [[DavidJanes]]

* [[User:RobertBachmann|Robert Bachmann]]: “MUST” or at least “SHOULD” because atom:author is specified as “The "atom:author" element is a Person construct that indicates the author of the entry or feed.” and <code><address></code>’s semantics are too loose to describe [http://atompub.org/2005/08/17/draft-ietf-atompub-format-11.html#rfc.section.3.2 an Atom person construct] but using <code><addr class="vcard"></code> we would have pretty good 1:1 mappings:
** atom:name ↔ hCard’s FN
** atom:email ↔ hCard’s EMAIL
** atom:uri ↔ hCard’s URI

'''STATUS - OPEN'''. "MAY" is the answer.

Tantek: I think this should be MUST. Atom should have referenced vCard for these semantics and made the mistake of making up their own terms. Let's undo that mistake with hAtom. Also, [[hreview|hReview]] 0.3 is going to make hCard a MUST for the "reviewer" property, based on experience and [[hreview-feedback|feedback]]. Thus we may want to just follow suit with hAtom as well.

DavidJanes: I had based the behavior on hReview 0.2. The problem is getting meaningful information into the blog templates and also I would appeal to parsimony, that is:

<pre><nowiki>
<div class="author">bonehead</div>
</nowiki></pre>

has an assumed defined mapping to

<pre><nowiki>
<div class="author vcard"><span class="fn">bonehead</div></div>
</nowiki></pre>

Since in many cases we're not going to get much more information than that, why add the verbosity? I note an analogous situation in hCard, where N.* are not required because they can be inferred algorithmicly.

== Comparisons ==

This seems precisely analogous to [http://www.meyerweb.com/eric/tools/s5/xoxo-structure-ref.html S5]:
* atomentry <-> slide
* content <-> slidecontent
* summary <-> handout
I'm all for NOT boiling the ocean, but these really seem like the same cup of tea.

-- [[Ernie Prabhakar]]

* See the [[#Purpose]] section above. Basically that drove the design decision for the naming [[User:DavidJanes|David Janes]]

'''STATUS - RESOLVED'''. We're sticking with atom terminology (entry, content, summary).

See above as David says. The atom terminology is both problematic, and doesn't make sufficient reuse of existing microformat terminology. As far as the analogy to S5, yes, there is an analogy, but that doesn't make them the same. The semantics that are represented are different enough to let these evolve independently and see if content authors want them to converge or not. Note that you can overlay hAtom and S5 in the same markup. Anyone that is serious about converging these should *try* using both at the same time in a *real* slide presentation example and report back their experience. - Tantek

== Repeated Elements ==
We allow certain elements to be repeated, such as Entry Permalink, Entry Published and Entry Title, even though there can be at most one real value. We provide "disambiguation" rules for sorting out which is the real value. See [[hatom#Nesting_Rules|here]], [[hatom#Entry_Title|here]], [[hatom#Entry_Permalink|here]] and [[hatom#Entry_Published|here]].

Your thoughts please... -- [[User:DavidJanes|David Janes]]

'''STATUS - RESOLVED'''. The spec has explicit rules for disambiguating all these items if they appear multiple times.

== Opaqueness ==
If you have concerns about [[hatom#hAtom_Opaque|opaqueness]], that is, stopping interpretation below certain hAtom elements, raise them here.

=== Opaqueness of other microformat elements ===
How would we handle a case where someone wanted to provide a vcard under the class=entry element for an individual who was neither author or contributor? Consider the hypothetical case where someone wanted to list their "muse" alongside article author and contributors. If this vcard included a title it might be included accidentally as an <atom:title>.

To summarise,
Is it possible that other microformats found under the class=entry or class=feed elements need to be considered opaque?

-- BenjaminCarlyle

* The issue of "muse" and such is somewhat out of scope. However, I grasp your larger point -- what if we wanted to extend or compositie hAtom in the future. Given the 80-20 rule right now, my feeling is to set aside the problem and if it arises, define a <code>class="opaque"</code> element. -- [[User:DavidJanes|David Janes]]

See the [[mfo-examples]] document, and add further thoughts on this matter there. -- Tantek

=== Opaqueness of summary and content ===
What one publisher considers the entry content may differ from another publisher's point of view. Is the content simply a div that does not contain any author/updated/published metadata etc, or could some of that metadata be relevant to the content as well as the entry? Consider updated. last-modified-brainstorming introduces an idea of using <code><ins></code> and <code><del></code> elements to indicate update time. Updates are also often included in entry content with further information. This suggests to me that the line of opaqueness is blurry.

Perhaps content and summary should not be opaque, and instead rely on the mfo proposal to avoid parsing into microformats below the content level. This approach would allow a single div to contain both "entry" and "content" classes should all metadata be considered content by the author, or would permit any other subset of the metadata to be considered content without repeating one's self.

Consider also the "read more"-style blog. The following nesting of div elements is illegal under current opacity rules:
<code><div class="content"><div class="summary">...</div>...</div></code>

A further example is provided by _fil_ on #microformats, who uses the rel-tag microformat within his atom:content to be handled as tags in his feed reader.

== Identification ==
The current spec under Schema:Nomenclature:Entry includes the text:
"if practical, also define id="unique-identifier" to the Entry"
What should be done with this id by parsers? How does this interact (if at all) with the interpretation of a rel=bookmark within the entry?

Also, how should a feed <id> element be filled out from a hAtom source document? Is a rel=bookmark at the feed level required?

The id elements in atom are supposed to survive all future movements of the blog t new hosting arragements and the like. Are current feed URLs or even rel=bookmarks solid enough?

'''STATUS - OPEN'''.

== HTML Title ==
Atom permits title to be either plain text or html. hAtom2Atom.xsl currently uses a plain text translation, and some feed readers seem not to handle html titles well (liferea does not normalize-whitespace, for example). Should a hAtom title element become a plain text or a html atom title? If so, should a subset of html be passed through rather than all html (including id, etc)?

== rel-tag ==
Should hAtom use rel-tag for atom category elements?

IMHO yes. -- Tantek

A version of this is currently implemented in hAtom2Atom.xsl, but the interpretation of rel-tag is not straightforward.

rel-tag uses the last path segment of a URI as its tag, for example <code><a href="http://apple.com/ipod" rel="tag">iPod</a></code>. Human-friendly content is permitted within the anchor. Atom defines three attributes on a category element. "term" is the category in use. "scheme" is a namespace for this category. "label" is a human-friendly text-only version of the category.

* This looks like a clear mapping to me - term is last path segment; scheme is the tagspace and label is the text within the anchor? The problem is if the scheme + tag is not a true URL but a URI. So for your example, term is 'ipod, scheme is 'http://apple.com/' and label is iPod. [[User:Kevin Marks|Kevin Marks]] 15:03, 31 Dec 2005 (PST)

hAtom2Atom.xsl does not currently supply a scheme. Label is taken from the content of the anchor tag, and no special handling for content such as the title attribute of an img element is performed. Term is the portion of the href after the last slash character.

rel-tag permits url encoding for IRIs, as well as conversion of spaces to plus (+) characters. It is unclear whether the conversion of rel-tag data to atom:category/@term should attempt to reverse any such encoding. The handling of plus characters may be especially difficult to reverse (are the plus characters, or spaces?).

* They are spaces. If you want plus characters use %2B Perhaps I should add this to rel-tag. [[User:Kevin Marks|Kevin Marks]] 15:03, 31 Dec 2005 (PST)

== Excess disambiguation rules? ==
Disambiguation rules apply to feed and entry title, and hAtom2Atom.xsl implements these. Rules also apply to permalink, published, and updated. These are currently not implemented. If they appear multiple times in the source document they are repeated multiple times.

It is clear that the data relating to these fields may be repeated within a hAtom entry, however the class notation may not. Only one element need be marked with rel="bookmark". Only one need be marked published, and one updated. Should the disambiguation rules be removed and only one element be allowed for each value, or is there value to the publisher in marking different elements with the hAtom class names?

== Dependancies ==
=== mfo ===
Does this specification depend on acceptance of a hAtom-compatible mfo?
See [[mfo-examples]].

=== last-modified ===
Does this specification depend on acceptance of a hAtom-compatible last-modified?

== Is atom:content necessary? ==
Atom's structure is built up around separating content and other metadata. atom:updated, atom:author, and the like are separate from atom:content any may contain repeated data. Microformats are built around bringing the content and the metadata back together. Is there are genuine use case for identifying only part of the atom entry as content? Presumably the whole html entry is fit for human consumption, or it wouldn't be part of a microformatted web page. Could that whole html snippet be used as the content?

== Published as default value for atom:updated ==
It seems to be common practice to include an "updated" section within the main blog content to track updates to an atom:entry as they occur. It is less common to include a value for atom:published within atom:content. atom:published is usually provided by a machine, but atom:updated is often provided by a human.

I suggest that if a value of published exists but no value for updated exists that the required updated field be filled out from the optional published field. I think this would make changing the required value of updated easier for publishers. Also, several updates may occur to a single entry. I suggest that a disambiguation rule be applied such that the the latest timestamp of any updated field be used if several exist. The overal parser semantics would therefore be:
# If multiple updated fields exist, choose the most recent one.
# If only one updated field exists, choose that value.
# If no updated field exists but a published field exists, use the published value for atom:updated.

=See Also=
* [[hatom|hAtom]] - the draft proposal
* [[hatom-issues]] - problems? complaints? ideas? Put them here
* [[hatom-faq]] - knowledge base
* [[blog-post-brainstorming]]
* [[blog-post-formats]]
* [[blog-post-examples]]
* [[blog-description-format]] - how to describe a blog (as opposed to the individual entries, which is what we're doing here)
* [[mfo-examples]]
* [[naming-principles]]

hcard

2005-12-22T19:57:11Z

Atamido: Added links to other hCard wiki pages.

= hCard =

hCard is a simple, open, distributed contact information format for people, companies, and organizations, which is suitable for embedding in (X)HTML, Atom, RSS, and arbitrary XML. hCard is a 1:1 representation of the vCard standard ([http://www.ietf.org/rfc/rfc2426.txt RFC2426]) in XHTML, one of several open [[microformats|microformat]] standards.
__TOC__

== Draft Specification ==

=== Editor ===
[http://tantek.com/ Tantek Çelik], [http://technorati.com Technorati, Inc.]

=== Authors ===
* [http://tantek.com/ Tantek Çelik], [http://technorati.com Technorati, Inc]
* [http://suda.co.uk/ Brian Suda]

=== Copyright ===
{{MicroFormatCopyrightStatement2004}}

=== Patents ===
{{MicroFormatPatentStatement}}

=== Inspiration and Acknowledgments ===
Thanks to: my good friend [http://vadim.com/ Vadim] who introduced me to vCard ''many'' years ago, and if I'd only paid more attention then, perhaps I could have helped a lot of people avoid wasting a lot of time reinventing various standards wheels.

== Introduction ==
The vCard standard ([http://www.ietf.org/rfc/rfc2426.txt RFC2426]), has been broadly interoperably implemented (e.g. Apple's "Address Book" application built into MacOSX).

In addition, many bloggers identify themselves by name and discuss their friends and family. With just a tad bit of structure, bloggers can discuss people in their blog(s) in such a way that spiders and other aggregators can retrieve this information, automatically convert them to vCards, and use them in any vCard application or service.

This specification introduces the '''hCard''' format, which is a 1:1 representation of the aforementioned vCard standard, in semantic XHTML. Bloggers can both embed vCards directly in their web pages, and style them with CSS to make them appear as desired. In addition, hCard enables applications to retrieve information about such vCards directly from web pages without having to reference a separate file.

Use the [http://microformats.org/code/hcard/creator hCard creator], copy the HTML code it generates to your blog or website to publish your contact info.

== Semantic XHTML Design Principles ==
{{semantic-xhtml-design-principles}}

== Format ==
=== In General ===
The vCard standard ([http://www.ietf.org/rfc/rfc2426.txt RFC2426]) forms the basis of hCard.

The basic format of hCard is to use vCard object/property names in lower-case for class names, and to map the nesting of vCard objects directly into nested XHTML elements.

=== More Semantic Equivalents ===
However, for some properties there is a more semantic equivalent, and therefore they get special treatment, e.g.:
* <code>URL</code> in vCard becomes <code><a class="url" href="...">...</a></code> inside the element with <code>class="vcard"</code> in hCard.
* Similarly, <code>EMAIL</code> in vCard becomes <code><nowiki><a class="email" href="mailto:...">...</a></nowiki></code>
* <code>PHOTO</code> in vCard becomes <code><img class="photo" src="..." alt="Photo of ..." /></code>

=== Singular vs. Multivalued Properties ===

For properties which are singular (e.g. "N" and "FN"), the first descendant element with that class should take effect, any others being ignored.

For properties which can be plural (e.g. "TEL"), each class instance should create a instance of that property.

==== Plural Properties Singularized ====

Since plural property names become their singular equivalents, even if the original plural property permitted only a single value with multiple components, those multiple components are represented each with their own singularly named property and the the property is effectively multivalued and subject to the above treatment of multivalued properties.

=== Human vs. Machine readable ===

If an <code><abbr></code> element is used for a property, then the '<code>title</code>' attribute of the <code><abbr></code> element is the value of the property, instead of the contents of the element, which instead provide a human presentable version of the value.

Similarly, if an <code><img></code> element is used for one or more properties, it must be treated as follows:
# For the "PHOTO" property and any other property that takes a URL as its value, the <code>src="..."</code> attribute provides the property value.
# For other properties, the <code><img></code> element's '<code>alt</code>' attribute is the value of the property.

=== Value excerpting ===

Sometimes only part of an element which is the equivalent for a property should be used for the value of the property. This typically occurs when a property has a subtype, like TEL. For this purpose, the special class name "<code>value</code>" is introduced to excerpt out the subset of the element that is the value of the property. E.g. here is an hCard fragment for marking up a home phone number:

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

This hCard fragment could be displayed as:

home: +1.415.555.1212

=== Property Exceptions ===

vCard has several properties which either do not make sense on, or are already implied within the context of a web page. This section explains what to (not) do with them.

# '''NAME''', '''PROFILE''', '''SOURCE''', '''PRODID''', '''VERSION''' properties as defined in Sections 2.1.2, 2.1.3, 2.1.4, 3.6.3, 3.6.9 of RFC 2426. Content publishers MUST NOT use these properties in their hCards, and as such, hCard consumers/parsers MUST IGNORE these properties if they are found within an hCard. Instead. hCard to vCard converters SHOULD use the title of the page where the hCard is found (e.g. the <code><title></code> element in (X)HTML documents) to construct the NAME property, MAY output a PROFILE value of "<code>VCARD</code>" per RFC 2426, SHOULD use the URL of the page where the hCard is found to construct the SOURCE property (e.g. perhaps as a parameter to a URL/service that converts hCards to vCards), for an output vCard stream (e.g. a .vcf file). Only services/applications that output actual vCards should write the PRODID property, with the product identifier for said service/application. Similarly only such services/applications should write the VERSION property, with the value "3.0" (without quotes) per RFC2426 Section 3.6.9.

=== Implied "N" Optimization ===

Although vCard requires that the "N" property be present, the authors of the vCard specification (RFC 2426) themselves do not include "N" properties in their vCards near the end of the spec (p.38). This apparent contradiction can be resolved by simply allowing the "FN" property to imply "N" property values in typical cases provided in the spec. We do so explicitly in hCard.

If the value of the "FN" property is exactly two words (separated by whitespace.), and there is no explicit "N" property, then the "N" property is inferred from the "FN" property. For "FN"s with either one word or three or more, then the author MUST explicitly markup the "N", except for the organization contact info case, [http://microformats.org/wiki/hcard#Organization_Contact_Info see below] for that.

# The content of "FN" is broken into two "words" separated by whitespace.
# The ''first'' word of the "FN" is interpreted as the "Given Name" for the "N" property.
# The ''second/last'' word of the "FN" is interpreted as the "Family Name" for the "N" property.
# Exception: If the first word ends in a "," comma OR if the second word is a single character (optionally followed by a period "."), then the first word (minus the comma at the end if any) is interpreted as the "Family Name" and the second word is interpreted as the "Given Name".

This allows simplification in the typical case of people stating their firstname space lastname, or lastname comma firstname, or lastname comma firstinitial, or lastname space firstinitial.

==== Organization Contact Info ====

Contact info for a company or organization is a special case of the implied "N" optimization.

If the "FN" and "ORG" properties have the exact same value (typically because they are set on the same element, e.g. class="fn org"), then the hCard represents contact information for a company or organization and should be treated as such. In this case the author MUST also NOT set the "N" property, or set it (and any sub-properties) explicitly to the empty string "". Thus parsers should handle the missing "N" property in this case by implying empty values for all the "N" sub-properties.

=== Implied "organization-name" Optimization ===

The "ORG" property has two subproperties, organization-name and organization-unit. Very often authors only publish the organization-name. Thus if an "ORG" property has no "organization-name" inside it, then its entire contents MUST be treated as the "organization-name".

=== Root Class Name ===

The root class name for an hCard is "vcard".

=== Property List ===

This is the list of properties (and subproperties, in parantheses, like this) in hCard, taken from vCard:

* fn, n (family-name, given-name, additional-name, honorific-prefix, honorific-suffix), nickname, sort-string
* url, email (type, value), tel (type, value)
* adr (post-office-box, extended-address, street-address, locality, region, postal-code, country-name, type, value), label
* geo (latitude, longitude), tz
* photo, logo, sound, bday
* title, role, org (organization-name, organization-unit)
* category, note
* class, key, mailer, uid, rev
==== type subproperty values ====

The 'type' subproperty in particular takes different values depending on which property it is a subproperty of. These 'type' subproperty values are case-INSENSITIVE, meaning "Home" is the same as "home", as well as multivalued, e.g. a tel can be home and preferred:
<pre><nowiki>
<span class="tel"><span class="type">Home</span> (<span class="type">pref</span>erred):
<span class="value">+1.415.555.1212</span>
</span>
</nowiki></pre>

The following lists are ''informative''. See RFC2426 sections 3.2.1 ADR, 3.3.1 TEL, and 3.3.2 EMAIL respectively for normative type values. They are repeated here for convenience. Default type subproperty value(s) is(are) first in each list and indicated in ALL CAPS. types may be multivalued.

* adr type: INTL, POSTAL, PARCEL, WORK, dom, home, pref
* tel type: VOICE, home, msg, work, pref, fax, cell, video, pager, bbs, modem, car, isdn, pcs
* email type: INTERNET, x400, pref, "other IANA registered address types"

=== XMDP Profile ===

See [[hcard-profile]] for the [http://gmpg.org/xmdp XMDP] profile of hCard which contains the above complete list of properties, with references to their RFC 2426 definitions.

=== Parsing Details ===

See [[hcard-parsing|hCard parsing]].

== Examples ==

This section is informative.

=== Sample vCard ===

Here is a sample vCard:

<pre><nowiki>
BEGIN:VCARD
VERSION:3.0
N:Çelik;Tantek
FN:Tantek Çelik
URL:http://tantek.com
ORG:Technorati
END:VCARD
</nowiki></pre>

and an equivalent in hCard with various elements optimized appropriately. See [[hcard-example1-steps| hCard Example 1]] for the derivation.

<pre><nowiki>
<div class="vcard">
<a class="url fn" href="http://tantek.com/">Tantek Çelik</a>
<div class="org">Technorati</div>
</div>
</nowiki></pre>

This hCard might be displayed as:

[http://tantek.com/ Tantek Çelik]<br />
Technorati

Note: The version information is unnecessary in hCard markup directly since the version will be defined by the profile of hCard that is used/referred to in the 'profile' attribute of the <head> element.

=== More Examples ===

See [[hcard-examples]] for more examples, including all examples from vCard RFC 2426 converted into hCard.

== Examples in the wild ==
This section is '''informative'''.

The following sites have published hCards, and thus are a great place to start for anyone looking for examples "in the wild" to try parsing, indexing, organizing etc. If you have an hCard on your own page, feel free to add it to the top of this list. Once the list grows too big, we'll make a separate wiki page.

* [http://www.go-curiosity.com/about.htm Piercarlo Slavazza] has published an hCard.
* [http://richi.co.uk/blog/2005/12/structured-blogging.html Richi Jennings] has put up his attempt
* [http://www.shiftingpixel.com/about/ shifting pixel photoblog] has published an hCard.
* [http://www.paradigmproductions.org/contact/ Paradigm Productions] published a vcard as a ul (marked up by [http://www.linkingarts.com/ Peter Jacobson])
* [http://www.bath.ac.uk/contact/ University of Bath] Person Finder results are encoded with hCards so you can easily create a vCard from any result.
* [http://chrischerry.name/blog/contact/ Chris Cherry's contact page with his hCard]
* [http://tagcamp.org/index.cgi?ContactList TagCamp contact list]
* [http://landsbank.fo/#hCard Landsbanki Føroya]
* [http://www.iowamilitaryveteransband.com/members/ Iowa Military Veterans Band Contacts] - 95 hCards [http://weblog.randomchaos.com/archive/2005/10/24/Microformats/ marked up by Scott Reynen]
* [http://rbach.priv.at/Contact Robert Bachmann] has published his hCard and [http://rbach.priv.at/Images/hcard a button].
* The good ship [http://styrheim.com/test/leonid.html Leonid Miloslavskiy] spotted in the North Atlantic
** INVALID --[[User:RyanKing|RyanKing]] 00:50, 27 Oct 2005 (PDT)
*** class="family" should probably be family-name
*** the "n" property is missing and the "n" optimization can't be applied
*** the first geo propery is empty, the second one is invalid (ie, it doesn't contain lat/long)

* [http://tantek.com/microformats/2005/web2/speakers.html Web 2.0 Conference speakers page marked up with hCard]

* [http://www.ndunn.com Neil Dunn] has published his rather [http://www.ndunn.com/2005/10/7/hCard good looking hCard]

* [http://we05.com/ Web Essentials 05] marked up all their [http://we05.com/presenters.cfm presenters with hCard].
* [http://twinsparc.com/ Twinsparc] put an hCard in the header and footer of all their pages.
** (2005-09-27) No FN and no ORG properties
** (2005-10-07) Fixed

* [http://www.oliverbrown.me.uk/ Oliver Brown] has published his hCard.
** (2005-09-27) PASSED

* [http://suda.co.uk/ Brian Suda] has managed to embed a photo in [http://suda.co.uk/contact/ his hCard] through the [http://www.ietf.org/rfc/rfc2397.txt data uri scheme] by converting the image to BASE64 code. View the Source to see how this is accomplished. [http://suda.co.uk/projects/X2V/get-vcard.php?uri=http%3A//suda.co.uk/contact/ The X2V link] will extract the image and encode it for a vCard which will be displayed in some address book applications.

* [http://www.efas.fupl.asso.fr/efas/_Mathieu-Drouet_.html Mathieu Drouet] and [http://www.efas.fupl.asso.fr/efas/_Annie-Leger_.html Annie Leger] both have hCards
** (2005-09-27) PASSED, PASSED

* [http://www.paulmichaelsmith.com/blog/hcard.htm Paul Smith] has created an hCard page which is Human Readable, and a link to X2V passing the same hCard page to generate a vCard.
** (2005-09-27) PASSED

* [http://loadaveragezero.com/hnav/contact.php Douglas W. Clifton] added all types of contact information
** (2005-09-27) PASSED

* [http://kinrowan.net/ Cori Schlegel] [http://kinrowan.net/blog/wp/archives/2005/07/08/a-problem-with-the-structured-blogging-plug-in-for-wordpress/ discusses how he has updated] [http://kinrowan.net/blog/contact his contact page with hCard]
* [http://thoughtport.blogspot.com/ Aiden Kenny] hasn't published his hCard yet, but he has [http://thoughtport.blogspot.com/2005/07/elemental-particles-of-web.html published his hCard icon]: http://photos1.blogger.com/blogger/4224/444/320/AK-Hcard-icon.gif
* [http://JackWolfgang.blogspot.com Jack L. Wolfgang II] has [http://jack.randomata.com/resume/ converted the addresses in his resume to hCards].
** Please re-check (resume moved and updated)

* [http://www.kerihenare.com/ Keri Henare] has marked up his [http://www.kerihenare.com/contact/ contact info page] with hCard.
** (2005-09-27) PASSED
** (2005-11-01) hCard completely rewritten

* [http://www.windley.com/archives/2005/07/hcards_trying_o.shtml Phil Windley has published] [http://phil.windley.org/hcard.html his hCard].
** (2005-09-27) PASSED

* Cori Schlegel has published a full hCard on his [http://kinrowan.net/contact contact page] and an abbreviated version (linked to the full version) in the sidebar of his [http://kinrowan.net blog].
* [http://cinematreasures.org Cinema Treasures] uses hCard to markup venue information for 10,000+ movie theaters.
* [http://thedredge.org Andy Hume] uses the hcard format to mark-up the names and URLs of commentors on his blog.
* [http://www.wolfsreign.com Steven Ametjan] has published his hCard on [http://www.wolfsreign.com/about/ his about page].
** (2005-09-27) PASSED

* [http://evdb.com EVDB], the Events and Venues Database, publishes all venue detail pages with embedded hCards.
* [http://paulschreiber.com/blog/ Paul Schreiber]'s [http://concerts.shrub.ca/ Sunnyvale House Concerts] site publishes hCards for upcoming artists, as well as an hCard for the page itself. In addition the [http://concerts.shrub.ca/shows Past Shows] page contains hCards for all past artists.
** (2005-09-27) PASSED

* [http://zooibaai.nl/ Rob Mientjes] has published his hCard on [http://zooibaai.nl/about/ his about page].
** (2005-09-27) PASSED

* [http://gbraad.nl/ Gerard Braad] has published an example on his [http://gbraad.nl/site/?p=profile profile] page that is almost consistent with his original [http://gbraad.nl/files/gbraad.vcf vCard] file. Also progress is made for transforming his [http://files.gbraad.nl/foaf.rdf FoaF] file to a hCard encoded representation. (also done for my spouse:[http://spouse.gbraad.nl/site/?p=profile Yong Yuan])
** (2005-09-27) PASSED, PASSED

* [http://doncrowley.blogspot.com/ Don Crowley] has published [http://www.crowley.nl/hcard.html his hCard] as well as a nifty hCard button: http://www.crowley.nl/images/hcard.png
** (2005-09-27) PASSED

* [http://technorati.com/ Technorati]'s [http://www.technorati.com/about/ About page] lists their '''Media Contact'''
** (2005-09-27) PASSED

* [http://tantek.com/log Tantek's Thoughts] includes an inline author hCard at the bottom of the page.

* Paul Schreiber has published his hCard on [http://paulschreiber.com/about/?contact his about page].
* Scott Reynen has published his hCard on [http://www.randomchaos.com/document.php?source=scott_reynen his profile page].
* [http://www.w3.org/People/Connolly/events/ Dan Connolly's index of events and talks] has hCards for many of the people he has met at those events.

* [http://www.bidclix.com/ BidClix]'s [http://www.bidclix.com/AboutContact.html Contact BidClix] page has it's ''contact info'' marked up with an hCard.

== Implementations ==
This section is '''informative'''.

The following implementations have been developed which either generate or parse hCards. If you have an hCard implementation, feel free to add it to the top of this list. Once the list grows too big, we'll make a separate wiki page.

* There is [http://flickr.com/photos/factoryjoe/68755089/ evidence of built-in hCard support in the Konqueror browser]. Specifically, Konqueror 3.5, in KDE 3.5 (kubuntu Breezy w/ update).
* There is [http://tagcamp.org/index.cgi?ContactList evidence of a kwiki plugin for hCards]. Update: the [http://svn.kwiki.org/cwest/Kwiki-hCard/ hCard kwiki plugin svn repository]. See the [http://microwiki.caseywest.com/index.cgi?hCard documentation of the hCard kwiki plugin].
* [http://suda.co.uk/projects/X2V/ X2V] is a bookmarklet that parses hCard and produces a .vcf (vCard) stream. Note: needs to be updated as the spec is refined
* [http://www.stripytshirt.co.uk Duncan Walker] has built [http://www.stripytshirt.co.uk/features/firefox/smartzilla a Firefox extension] that gets hCard data from a webpage, uses Brian Suda's XSL (locally) to transform it to vcard format and opens the resulting .vcf file.
* [http://george.hotelling.net/90percent/ George] has written a [http://george.hotelling.net/90percent/geekery/greasemonkey_and_microformats.php Greasemonkey user script] that detects hCards and allows users to easily add them to their address book application. Relies on the X2V web service to do the conversion.
* [http://blogmatrix.blogmatrix.com/ David Janes] has written a [[Greasemonkey]] [http://www.blogmatrix.com/include/microformat-find.user.js script] that finds many microformat elements, including hCards, and [http://blog.davidjanes.com/mtarchives/2005_08.html#003376 provides a popup menu of actions]. The hCard to vCard conversion is done internally within the script. ''This does not work with FireFox 1.5+/GreaseMonkey 0.6.4+.''
* [http://diveintomark.org/ Mark Pilgrim] has also written an [http://diveintomark.org/projects/greasemonkey/hcard/ hCard parser Greasemonkey user script]. It is self-contained and does not rely on the X2V web service.
* [http://www.oliverbrown.me.uk/2005/09/03/a-working-microformats-extension-to-simplexml/ Oliver Brown] has written an "extension" to [http://www.php.net/simplexml SimpleXML] that gives simple access to hCard information in PHP 5.
* [http://thedredge.org/ Andrew D. Hume] has built a system (Wordpress plugin?) for [http://thedredge.org/2005/06/using-hcards-in-your-blog/ using hcards in your blog] to represent people leaving comments on blog posts.
* The [http://tantek.com/microformats/hcard-creator.html hCard creator] is a very simple, yet illustrative, open source user interface / form / script which creates an hCard in real-time as you type in a set of contact information.
* [http://greenbytes.de/tech/webdav/rfc2629.xslt rfc2629.xslt] now attempts to generate hCard information ([http://ietf.org/rfc/rfc2629 RFC2629] is an XML format for authoring RFCs and Internet Drafts, see [http://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html example document])
* [http://tantek.com/microformats/buddylist2hcards.html iChat buddy list to hCards] - Open source AppleScript to automatically convert one's buddy list in the MacOSX iChat AIM client into a valid XHTML 1.0 Strict list of hCards.
* [http://dev.w3.org/cvsweb/2001/palmagent/ palmagent] is a collection of palmpilot and sidekick tools. It includes X2V derivatives xhtml2hcard.xsl and toICal.xsl plus some [http://dev.w3.org/cvsweb/2001/palmagent/hcardTest.html hcardTest] materials
* [http://www.openpsa.org/ OpenPsa 2.x] CRM application uses hCard for all person listings. The widget is [http://www.midgard-project.org/midcom-permalink-922834501b71daad856f35ec593c7a6d reusable across Midgard CMS]

== Additional Applications ==
This section is '''informative'''.

There are numerous potential additional uses and applications for hCards on the Web. The following are merely a few thoughts and possibilities that folks have come up with:

* As an open standard/format for [http://www.gravatar.com/ Gravatars].
* Marking up individual authors of blog posts on a group blog
* Marking up people's names and URLs in a blogroll
* Any reference to people in blog posts (e.g. when citing them, or referencing them, or describing them, by name).
* ...

== References ==
=== Normative References ===
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]
* [http://www.ietf.org/rfc/rfc2426.txt vCard RFC2426]

=== Informative References ===
* [http://www.w3.org/2002/12/cal/rfc2426 HTML reformatted version of RFC2426]
* [http://w3.org/TR/REC-CSS1 CSS1]
* [http://tantek.com/log/2004/09.html#hcard hCard term introduced and defined on the Web, 20040930]
* [http://wiki.oreillynet.com/foocamp04/index.cgi?SimpleSemanticFormats FOO Camp 2004 Simple Semantic Formats presentation, 20040910]
* Contributed from http://developers.technorati.com/wiki/hCard.
* [http://www.w3.org/TR/xhtml11 XHTML 1.1]

==== Specifications That Use hCard ====
* [[adr]]
* [[geo]]
* [[hcalendar|hCalendar]]
* [[hreview|hReview]]

==== hCard Wiki Pages ====
* [[hcard-faq]]
* [[hcard-issues]]
* [[hcard-tests]]
* [[hcard-brainstorming]]
* [[hcard-profile]]

==== Similar Work ====
* [http://www.intertwingly.net/wiki/pie/PaceBetterPersonElement Atom PaceBetterPersonElement]
* [http://www.jabber.org/jeps/jep-0054.html JEP-0054: vcard-temp]

== Work in progress ==
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added. There is a separate document where we are keeping our brainstorms and other explorations relating to hCard:

* [[hcard-brainstorming|hCard Brainstorming]]
* [[hcard-tests|hCard tests]]

== Discussions ==

* See [http://www.technorati.com/cosmos/referer.html blogs discussing this page].

=== Q&A ===
* If you have any questions about hCard, check the [[hcard-faq|hCard FAQ]], and if you don't find answers, add your questions!

=== Issues ===
* Please add any issues with the specification to the separate [[hcard-issues|hCard issues]] document.

hcard-issues

2005-12-22T07:26:50Z

Atamido: Added Outlook 2003 Windows

= hCard issues =

These are externally raised issues about [[hcard|hCard]] with broadly varying degrees of merit. Thus some issues are REJECTED for a number of obvious reasons (but still documented here in case they are re-raised), and others contain longer discussions. Some issues may be ACCEPTED and perhaps cause changes or improved explanations in the spec. Submitted issues may (and probably will) be edited and rewritten for better terseness, clarity, calmness, rationality, and as neutral a point of view as possible. Write your issues well. — [http://tantek.com/log/ Tantek]

See related [[hcalendar-issues]].

== Issues ==

* 2005-06-21 raised by Hixie
*# ''Issue H-1: This specification is lacking a user agent conformance section. There's basically nothing that says how hCards must be parsed, how to handle errors, and so forth. Is it defined in terms of the DOM? Is it defined in terms of a serialisation? How do you handle unexpected content or missing content?
*#*A: ACCEPTED RESOLVED. See [[hcard-parsing]] for how hCards must be parsed. For errors/unexpected content/missing content, please provide specific examples.

* 2005-06-30 raised by Jack L. Wolfgang II. Please feel free to move these to the FAQs if they are better suited there.
*# ''Handling middle names and suffixes: How does one handle middle initials/names in the hCard format and suffixes that are not honorific suffixes (e.g. Jr., Sr., II, III, etc. as opposed to Ph.D., Esq., M.D., etc.)?''
*#*A: ACCEPTED FAQ. By [http://suda.co.uk Brian Suda] (2005-11-08 updated by [http://tantek.com/log/ Tantek]) hCard is based of the RFC2426 spec. I you want to use a middle initial it can be expanded using the abbr element. <code><abbr title="Middle Name" class="additional-name">M</abbr></code>. Honorific Suffixes in the RFC include Jr. Esq. and other inherited suffixes, so i would just use <code><span class="honorific-suffix">Jr.</span></code> etc.
*# ''Handling different types of addresses: How does one handle the TYPE (e.g. postal, work, etc.) specification for addresses as specified in RFC 2426 Section 3.2.1?''
*#*A: ACCEPTED FAQ. By [http://suda.co.uk Brian Suda] (2005-11-08 updated by [http://tantek.com/log/ Tantek]) If you want to add a type to certain elements, including address and telephone it may be done in the following manner:
<pre><nowiki>
<span class="adr">
<span class="type">work</span>:
...
</span>
</nowiki></pre>
<pre><nowiki>
<span class="tel">
<span class="type">work</span>:
<span class="value">123.456.7890</span>
</span>
</nowiki></pre>
the TYPE needs to be a sub-element of the property (adr, tel, etc) NOTE: EMAIL does NOT have many TYPE attributes, only INTERNET and X400

* 2005-07-22 raised by DanConnolly
*# ''...in my cellphone/sidekick address book, I have a number of entries for companies. I wrote [http://dev.w3.org/cvsweb/2001/palmagent/asHCard.xsl asHCard.xsl] to convert the data from RDF to hCard, but I don't know what to do with entries for companies, since FN is mandatory in hCard.''
*#*A: ACCEPTED FAQ. This should be an FAQ. "How do I write an hCard for a company?" The vCard specification is silent on this point (entries for companies). Thus there are two options as far as the hCard standard is concerned:
*#*# Set "fn" and "org" to the same value. E.g. <code><span class="fn org">W3C</span></code> (recommended)
*#*# Set "org" as usual, and set "fn" explicitly to empty. E.g. <code><span class="fn"></span><span class="org">W3C</span></code> or
*#*#* Simply have no "fn", and on the parsing side, if there is no "fn" present, but there is an "org" property, then duplicate the "org" value as "fn"
*#*The last two options are effectively the same and are both not explicit and easily confusable with a "missing data" condition. Thus option 1 is preferred. For converting applications (hCard to vCard), they ''may'' consider using proprietary extensions to make the distinction explicit in generated vCards, based on either case 1 or 2 above. E.g. Apple's Address Book application supports the property: <code>X-ABShowAs:COMPANY</code>
*#*We are looking for descriptions of how other vCard supporting applications treat "company" vCards differently from "person" vCards. Please provide descriptions here:
*#** Address Book / MacOSX.3:
*#*** Export (e.g. drag & drop to desktop, view in text editor)
*#**** Sets "FN" and "ORG" to the name of the company
*#**** Sets proprietary <code>X-ABShowAs:COMPANY</code>
*#*** Import (e.g. edit in text editor, drag & drop from desktop)
*#**** By setting "FN" and "ORG' to the same name (e.g. Banana Computers Inc.)
*#**** And removing any proprietary properties (e.g. X-ABShowAs)
*#**** Address Book user interface showed new vCard as a "company" contact rather an a person
*#** Address Book MacOSX.4:
*#*** same results as above -RyanKing
*#** The Danger Hiptop (aka T-Mobile Sidekick) addressbook:
*#*** Export (e.g. [http://lists.w3.org/Archives/Public/www-archive/2005Sep/0007.html email to a mailing list])
*#**** Sets "FN" to the empty string and puts the company name in "ORG".
*#*** Import - could not find a way to import a .vcf, by email, IM, or other means into the Sidekick.
*#** Contacts / Outlook 2003 Windows
*#*** Export (e.g. Highlight contact, File, Save As, vcard)
*#**** Sets "N" and "ORG to the name of the company
*#**** Sets "FN" to value in "File as:"
*#** Add another vCard app here.

* 2005-07-23 raised by DanConnolly
*# ''Are class names case sensitive or not? [[hcard]] says "If names in the source schema are case-insensitive, then use an all lowercase equivalent."''
*#* A: ACCEPTED FAQ. Class names are case sensitive per the HTML4 specification. Hence hCard explicitly specifies the case of class name to use for source schema names that are case-insensitive.
*# ''...but I find example data with class="Given-Name"''
*#* A: ACCEPTED RESOLVED. That is from an older preliminary version of the hCard spec which used mixed case class names. Such class names are no longer valid hCard. Please note which examples (URLs) are using the older class names and hopefully we can get them fixed.
*#** A: By [http://suda.co.uk Brian Suda] I have fixed all the references in the [[hcard-brainstorming]] page to reflect the lower-case style, this is a hold-over from the original design, X2V has been updated.
*# ''..and code that supports it [data with class="Given-Name"].''
*#* A: ACCEPTED RESOLVED. Any code supporting the older class name(s) is for backward compatibility only, and should be phased out. Any new hCard code SHOULD NOT support such mixed case class names.
*#** [http://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html rfc2629xslt.html] uses Street-Address, Family-Name, etc.
*#*** A: By [http://greenbytes.de/tech/webdav/ Julian Reschke] Fixed rfc2629.xslt (2005-10-29)
*#** [http://suda.co.uk/projects/X2V/ X2V] Version 0.5.1 2005-07-08 supports Family-Name etc.
*#*** A: By [http://suda.co.uk Brian Suda] I agree that the upper-case class names can be removed from the code, this was a hold-over and will be trimmed.
*# ''The ul/ol stuff for multiple values of a property seems to be in the X2V code and in [[hcard-brainstorming]] but not in the [[hcard]] spec.''
*#* A. ACCEPTED RESOLVED. This needs to be added to the spec. 2005-11-08 Update: the way multiple values has been updated to work much better and not require ul/ol.
*# ''the [[hcard-profile]] says country-name but X2V and lots of the data I've seen says country''
*#* A. ACCEPTED RESOLVED. RFC 2426 clearly says "country name" in both the prose and the grammar, thus "country-name" is the correct class name to use. If X2V uses just "country", it needs to be fixed to use "country-name", and any such examples as well. Please note which examples (URLs) are using the class name "country" and hopefully we can get them fixed.
*#** A: By [http://suda.co.uk Brian Suda] I have fixed all the references in the [[hcard-brainstorming]] page to reflect the proper country-name, X2V will support this in the next iteration when i fix several bugs at once.

* 2005-08-12 raised by [http://home.alltel.net/jackwolfgang/contact/ Jack L. Wolfgang II]. Use of mailto transport functionality for the E-Mail address field.
*# ''As stated in the [[hcard-brainstorming]] document, mailto is abused by spammers. As a result, many organizations have moved to form-based contacts as opposed to mailto's. According to [http://www.ietf.org/rfc/rfc2426.txt RFC 2426], Section 3.3.2, "A non-standard value can also be specified." Does this refer to a non-standard e-mail address value or type value?''
*#* A: ACCEPTED FAQ. Type value.

* 2005-10-30 raised by [http://greenbytes.de/tech/webdav/ Julian Reschke].
*# ''Several implementations'' '''(Which ones? Please provide links.)''' ''seem to assume that any class attribute that contains the substring "vcard" indeed signals the presence of vcard information. Not so: there are examples'' '''(What examples? Please provide links.)''' ''of where a token in the class attribute indeed only ''starts with'' "vcard", in which it should be ignored. Implemenations using XPath (such as XSLT or Greasemonkey scripts) should be advised to do a <code>contains(concat(@class,' '),'vcard ')</code>.
*#* REJECTED VAGUE. Which implementations? And which examples?

* 2005-12-08 raised by [http://www.heatonarts.com Kenny Heaton].
*# ''The specification gives no way to to declare a telephone extention, as in (800) 234-5678 ext. 101''

== Template ==

Please use this format (copy and paste this to the end of the list to add your issues):
* YYYY-MM-DD raised by [http://yourhomepage.example.com YOURNAME].
*# ''Issue 1: Here is the first issue I have.''
*# ''Issue 2: Here is the second issue I have.''

existing-classes

2005-12-21T21:48:31Z

Atamido: Add internal links

<table>
<tr>
<th>Term</th>
<th>Parents</th>
<th>Children</th>
<th>Origin</th>
<th>Quick Definition</th>
</tr>
<tr>
<td>adr</td>
<td>vcard</td>
<td> country-name, extended-address, locality, postal-code, post-office-box, street-address,region, type, value </td>
<td>[[hCard]] </td>
<td>Address of the object. </td>
</tr>
<tr>
<td>bday </td>
<td>vcard</td>
<td></td>
<td>[[hCard]] </td>
<td>The birth date of the object. </td>
</tr>
<tr>
<td>category </td>
<td>vcard, hreview </td>
<td></td>
<td>[[hCard]] </td>
<td>Application category of the object.</td>
</tr>
<tr>
<td>class </td>
<td>vcard</td>
<td></td>
<td>[[hCard]] </td>
<td>The access classification of the object. For example, public or private. </td>
</tr>
<tr>
<td>country-name </td>
<td>adr, value </td>
<td></td>
<td>[[hCard]] </td>
<td>Name of the country for this particular address. </td>
</tr>
<tr>
<td>description</td>
<td>hreview</td>
<td></td>
<td>[[hReview]] </td>
<td>Full text of the description. (Not to be confused with the much longer "summary")</td>
</tr>
<tr>
<td>dtend </td>
<td>vevent </td>
<td></td>
<td>[[hCalendar]] </td>
<td>Ending date of the object. </td>
</tr>
<tr>
<td>dtreviewed</td>
<td>hreview</td>
<td></td>
<td>[[hReview]] </td>
<td>Date the review was written, NOT necessarily when the review took place. </td>
</tr>
<tr>
<td>dtstart</td>
<td>vevent </td>
<td></td>
<td>[[hCalendar]] </td>
<td>Starting date of the object. (Not to be confused with bday) </td>
</tr>
<tr>
<td>email </td>
<td>vcard, hreview </td>
<td> type, value</td>
<td>[[hCard]] </td><td>This object's email address. </td>
</tr>
<tr>
<td>extended-address</td>
<td>adr, value </td>
<td></td>
<td>[[hCard]] </td>
<td>Extended address for this particular address.</td>
</tr>
<tr>
<td>fn</td>
<td>vcard, hreview </td>
<td></td>
<td>[[hCard]]</td>
<td>The name of the object. </td>
</tr>
<tr>
<td>geo </td>
<td>vcard</td>
<td>latitude, longitude </td>
<td>[[hCard]] </td>
<td>Geographical coordinates of the object. </td>
</tr>
<tr>
<td>hreview </td>
<td>*webpage</td>
<td></td>
<td>[[hReview]]</td>
<td>A review of some object. </td>
</tr>
<tr>
<td>item </td>
<td>hreview</td>
<td></td>
<td>[[hReview]] </td>
<td>The item that the object exists for. For example, a review about Coca-Cola would list "Coca-Cola" as the item. </td>
</tr>
<tr>
<td>key </td>
<td>vcard</td>
<td>type, value </td>
<td>[[hCard]] </td>
<td>Public key of the object</td>
</tr>
<tr>
<td>label </td>
<td>vcard</td>
<td></td>
<td>[[hCard]] </td>
<td>Formatting to be used by a delivery address label. </td>
</tr>
<tr>
<td>latitude </td>
<td>geo</td>
<td></td>
<td>[[hCard]] </td>
<td>The latitude coordinates of the object. </td>
</tr>
<tr>
<td>locality </td>
<td>adr, value </td>
<td></td>
<td>[[hCard]] </td>
<td>Locality for this particular address. </td>
</tr>
<tr>
<td>location</td>
<td>vevent </td>
<td></td>
<td>[[hCalendar]] </td>
<td>Intended venue of object. (Not to be confused with adr) </td>
</tr>
<tr>
<td>logo </td>
<td>vcard</td>
<td></td>
<td>[[hCard]] </td>
<td>Object's logo. </td>
</tr>
<tr>
<td>longitude</td>
<td>geo</td>
<td></td>
<td>[[hCard]] </td>
<td>The longitude coordinates of the object. </td>
</tr>
<tr>
<td>mailer </td>
<td>vcard</td>
<td></td>
<td>[[hCard]] </td>
<td>Email software used by the object. </td>
</tr>
<tr>
<td>n </td>
<td>vcard</td>
<td> additional-name, family-name, given-name, honorific-prefix, honorific-suffix, nickname</td>
<td>[[hCard]] </td><td>The name of the unit </td>
</tr>
<tr>
<td>note </td>
<td>vcard</td>
<td></td>
<td>[[hCard]] </td>
<td>Supplemental information about the object. </td>
</tr>
<tr>
<td>org </td>
<td>vcard</td>
<td>organization-name, organization-unit</td>
<td>[[hCard]] </td><td>The organization or company of the object. </td>
</tr>
<tr>
<td>organization-name </td>
<td>org</td>
<td></td>
<td>[[hCard]] </td><td>The name of the organization or company of the object. </td>
</tr>
<tr>
<td>organization-unit </td>
<td>org</td>
<td></td>
<td>[[hCard]] </td><td>The unit or department of the object. </td>
</tr>
<tr>
<td>permalink </td>
<td>hreview</td>
<td></td>
<td>[[hReview]] </td>
<td>A link to the object. This link should never become invalid. Used in <a> </td>
</tr>
<tr>
<td>photo </td>
<td>vcard, hreview </td>
<td></td>
<td>[[hCard]] </td>
<td>A photo of the object. Used in <img> </td>
</tr>
<tr>
<td>post-office-box </td>
<td>adr, value </td>
<td></td>
<td>[[hCard]] </td>
<td>Post office box number of this particular address. </td>
</tr>
<tr>
<td>postal-code</td>
<td>adr, value</td>
<td></td>
<td>[[hCard]] </td>
<td>Postal code for this particular address. </td>
</tr>
<tr>
<td>profile</td>
<td>*webpage</td>
<td></td>
<td>XMDP</td>
<td>Contains metadata types and definitions. Used in <dl> </td>
</tr>
<tr>
<td>rating </td>
<td>hreview</td>
<td></td>
<td>[[hReview]] </td>
<td>Rating of 1-5 or 0-10 of the object. </td>
</tr>
<tr>
<td>region</td>
<td>adr, value </td>
<td></td>
<td>[[hCard]] </td>
<td>Region of this particular address. </td>
</tr>
<tr>
<td>rev </td>
<td>vcard</td>
<td></td>
<td>[[hCard]]</td>
<td>Specifies revision of the [[hCard]]. </td>
</tr>
<tr>
<td>reviewer </td>
<td>hreview</td>
<td>vcard</td>
<td>[[hReview]] </td>
<td>Person that wrote the review of the object. </td>
</tr>
<tr>
<td>role </td>
<td>vcard</td>
<td></td>
<td>[[hCard]] </td>
<td>Information regarding the role of the object. </td>
</tr>
<tr>
<td>sort-string </td>
<td>vcard</td>
<td></td>
<td>[[hCard]] </td><td>String used to sort this object in an alphabetical list. </td>
</tr>
<tr>
<td>sound </td>
<td>*any</td>
<td></td>
<td>[[hCard]] </td>
<td>Audio reading back another element's content. By default, the "fn". </td>
</tr>
<tr>
<td>street-address </td>
<td>adr, value </td>
<td></td>
<td>[[hCard]]</td>
<td>Street address of this particular address. </td>
</tr>
<tr>
<td>summary </td>
<td>vevent , hreview </td>
<td></td>
<td>[[hCalendar]] </td>
<td>A short summary or subject for the object. </td>
</tr>
<tr>
<td>tel </td>
<td>vcard</td>
<td> type, value</td>
<td>[[hCard]] </td>
<td>Telephone number of the object </td>
</tr>
<tr>
<td>title </td>
<td>vcard</td>
<td></td>
<td>[[hCard]] </td>
<td>Job title or functional position of the object.</td>
</tr>
<tr>
<td>type </td>
<td>adr, email, tel </td>
<td></td>
<td>[[hCard]] </td>
<td>Defines a type of the parent element. For instance a type of telephone number such as home or work.. Used in conjunction with "value". </td>
</tr>
<tr>
<td>tz </td>
<td>vcard</td>
<td></td>
<td>[[hCard]] </td>
<td>The timezone the object is in. </td>
</tr>
<tr>
<td>uid </td>
<td>*any</td>
<td></td>
<td>[[hCard]] </td>
<td>Globally unique identifier associated with the object, or one of the object's properties. </td>
</tr>
<tr>
<td>url </td>
<td>vcard, vevent , hreview </td>
<td></td>
<td>[[hCard]] </td>
<td>A link to the this object's home page or extended profile. Used in <a> </td>
</tr>
<tr>
<td>value </td>
<td>adr, email, tel </td>
<td></td>
<td>[[hCard]] </td>
<td>Used in conjunction with "type". The actual value of a particular type. For instance a telephone number of type work such as +1.415.555.1212. </td>
</tr>
<tr>
<td>vcalendar</td>
<td>*webpage</td>
<td>vevent</td>
<td>[[hCalendar]] </td>
<td>A list of calendar events. </td>
</tr>
<tr>
<td>vcard </td>
<td>*webpage, vevent </td>
<td></td>
<td>[[hCard]] </td>
<td>Indicates that this element and all containing elements are part of the [[hCard]] microformat. </td>
</tr>
<tr>
<td> vevent </td>
<td>*webpage, vcalendar </td>
<td></td>
<td>[[hCalendar]]</td>
<td>Indicates that this element and all contained elements are part of the [[hCalendar]] format. </td>
</tr>
<tr>
<td>version</td>
<td>hreview</td>
<td></td>
<td>[[hReview]] </td>
<td>Version of the format used for the object. </td>
</tr>
<tr>
<td>xoxo </td>
<td>*webpage</td>
<td></td>
<td>[[XOXO]]</td>
<td>An outline of data. Used in <ul> and <ol>. </td>
</tr>
</table>

existing-classes

2005-12-21T21:45:43Z

Atamido:

<table>
<tr>
<th>Term</th>
<th>Parents</th>
<th>Children</th>
<th>Origin</th>
<th>Quick Definition</th>
</tr>
<tr>
<td>adr</td>
<td>vcard</td>
<td> country-name, extended-address, locality, postal-code, post-office-box, street-address,region, type, value </td>
<td>[[hCard]] </td>
<td>Address of the object. </td>
</tr>
<tr>
<td>bday </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>The birth date of the object. </td>
</tr>
<tr>
<td>category </td>
<td>vcard, hreview </td>
<td></td>
<td>hCard </td>
<td>Application category of the object.</td>
</tr>
<tr>
<td>class </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>The access classification of the object. For example, public or private. </td>
</tr>
<tr>
<td>country-name </td>
<td>adr, value </td>
<td></td>
<td>hCard </td>
<td>Name of the country for this particular address. </td>
</tr>
<tr>
<td>description</td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>Full text of the description. (Not to be confused with the much longer "summary")</td>
</tr>
<tr>
<td>dtend </td>
<td>vevent </td>
<td></td>
<td>hCalendar </td>
<td>Ending date of the object. </td>
</tr>
<tr>
<td>dtreviewed</td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>Date the review was written, NOT necessarily when the review took place. </td>
</tr>
<tr>
<td>dtstart</td>
<td>vevent </td>
<td></td>
<td>hCalendar </td>
<td>Starting date of the object. (Not to be confused with bday) </td>
</tr>
<tr>
<td>email </td>
<td>vcard, hreview </td>
<td> type, value</td>
<td>hCard </td><td>This object's email address. </td>
</tr>
<tr>
<td>extended-address</td>
<td>adr, value </td>
<td></td>
<td>hCard </td>
<td>Extended address for this particular address.</td>
</tr>
<tr>
<td>fn</td>
<td>vcard, hreview </td>
<td></td>
<td>hCard</td>
<td>The name of the object. </td>
</tr>
<tr>
<td>geo </td>
<td>vcard</td>
<td>latitude, longitude </td>
<td>hCard </td>
<td>Geographical coordinates of the object. </td>
</tr>
<tr>
<td>hreview </td>
<td>*webpage</td>
<td></td>
<td>hReview</td>
<td>A review of some object. </td>
</tr>
<tr>
<td>item </td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>The item that the object exists for. For example, a review about Coca-Cola would list "Coca-Cola" as the item. </td>
</tr>
<tr>
<td>key </td>
<td>vcard</td>
<td>type, value </td>
<td>hCard </td>
<td>Public key of the object</td>
</tr>
<tr>
<td>label </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Formatting to be used by a delivery address label. </td>
</tr>
<tr>
<td>latitude </td>
<td>geo</td>
<td></td>
<td>hCard </td>
<td>The latitude coordinates of the object. </td>
</tr>
<tr>
<td>locality </td>
<td>adr, value </td>
<td></td>
<td>hCard </td>
<td>Locality for this particular address. </td>
</tr>
<tr>
<td>location</td>
<td>vevent </td>
<td></td>
<td>hCalendar </td>
<td>Intended venue of object. (Not to be confused with adr) </td>
</tr>
<tr>
<td>logo </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Object's logo. </td>
</tr>
<tr>
<td>longitude</td>
<td>geo</td>
<td></td>
<td>hCard </td>
<td>The longitude coordinates of the object. </td>
</tr>
<tr>
<td>mailer </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Email software used by the object. </td>
</tr>
<tr>
<td>n </td>
<td>vcard</td>
<td> additional-name, family-name, given-name, honorific-prefix, honorific-suffix, nickname</td>
<td>hCard </td><td>The name of the unit </td>
</tr>
<tr>
<td>note </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Supplemental information about the object. </td>
</tr>
<tr>
<td>org </td>
<td>vcard</td>
<td>organization-name, organization-unit</td>
<td>hCard </td><td>The organization or company of the object. </td>
</tr>
<tr>
<td>organization-name </td>
<td>org</td>
<td></td>
<td>hCard </td><td>The name of the organization or company of the object. </td>
</tr>
<tr>
<td>organization-unit </td>
<td>org</td>
<td></td>
<td>hCard </td><td>The unit or department of the object. </td>
</tr>
<tr>
<td>permalink </td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>A link to the object. This link should never become invalid. Used in <a> </td>
</tr>
<tr>
<td>photo </td>
<td>vcard, hreview </td>
<td></td>
<td>hCard </td>
<td>A photo of the object. Used in <img> </td>
</tr>
<tr>
<td>post-office-box </td>
<td>adr, value </td>
<td></td>
<td>hCard </td>
<td>Post office box number of this particular address. </td>
</tr>
<tr>
<td>postal-code</td>
<td>adr, value</td>
<td></td>
<td>hCard </td>
<td>Postal code for this particular address. </td>
</tr>
<tr>
<td>profile</td>
<td>*webpage</td>
<td></td>
<td>XMDP</td>
<td>Contains metadata types and definitions. Used in <dl> </td>
</tr>
<tr>
<td>rating </td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>Rating of 1-5 or 0-10 of the object. </td>
</tr>
<tr>
<td>region</td>
<td>adr, value </td>
<td></td>
<td>hCard </td>
<td>Region of this particular address. </td>
</tr>
<tr>
<td>rev </td>
<td>vcard</td>
<td></td>
<td>hCard</td>
<td>Specifies revision of the hCard. </td>
</tr>
<tr>
<td>reviewer </td>
<td>hreview</td>
<td>vcard</td>
<td>hReview </td>
<td>Person that wrote the review of the object. </td>
</tr>
<tr>
<td>role </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Information regarding the role of the object. </td>
</tr>
<tr>
<td>sort-string </td>
<td>vcard</td>
<td></td>
<td>hCard </td><td>String used to sort this object in an alphabetical list. </td>
</tr>
<tr>
<td>sound </td>
<td>*any</td>
<td></td>
<td>hCard </td>
<td>Audio reading back another element's content. By default, the "fn". </td>
</tr>
<tr>
<td>street-address </td>
<td>adr, value </td>
<td></td>
<td>hCard</td>
<td>Street address of this particular address. </td>
</tr>
<tr>
<td>summary </td>
<td>vevent , hreview </td>
<td></td>
<td>hCalendar </td>
<td>A short summary or subject for the object. </td>
</tr>
<tr>
<td>tel </td>
<td>vcard</td>
<td> type, value</td>
<td>hCard </td>
<td>Telephone number of the object </td>
</tr>
<tr>
<td>title </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Job title or functional position of the object.</td>
</tr>
<tr>
<td>type </td>
<td>adr, email, tel </td>
<td></td>
<td>hCard </td>
<td>Defines a type of the parent element. For instance a type of telephone number such as home or work.. Used in conjunction with "value". </td>
</tr>
<tr>
<td>tz </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>The timezone the object is in. </td>
</tr>
<tr>
<td>uid </td>
<td>*any</td>
<td></td>
<td>hCard </td>
<td>Globally unique identifier associated with the object, or one of the object's properties. </td>
</tr>
<tr>
<td>url </td>
<td>vcard, vevent , hreview </td>
<td></td>
<td>hCard </td>
<td>A link to the this object's home page or extended profile. Used in <a> </td>
</tr>
<tr>
<td>value </td>
<td>adr, email, tel </td>
<td></td>
<td>hCard </td>
<td>Used in conjunction with "type". The actual value of a particular type. For instance a telephone number of type work such as +1.415.555.1212. </td>
</tr>
<tr>
<td>vcalendar</td>
<td>*webpage</td>
<td>vevent</td>
<td>hCalendar </td>
<td>A list of calendar events. </td>
</tr>
<tr>
<td>vcard </td>
<td>*webpage, vevent </td>
<td></td>
<td>hCard </td>
<td>Indicates that this element and all containing elements are part of the hCard microformat. </td>
</tr>
<tr>
<td> vevent </td>
<td>*webpage, vcalendar </td>
<td></td>
<td>hCalendar</td>
<td>Indicates that this element and all contained elements are part of the hCalendar format. </td>
</tr>
<tr>
<td>version</td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>Version of the format used for the object. </td>
</tr>
<tr>
<td>xoxo </td>
<td>*webpage</td>
<td></td>
<td>XOXO</td>
<td>An outline of data. Used in <ul> and <ol>. </td>
</tr>
</table>

existing-classes

2005-12-21T21:44:01Z

Atamido: Classes already specified in microformats

<table>
<tr>
<th>Term</th>
<th>Parents</th>
<th>Children</th>
<th>Origin</th>
<th>Quick Definition</th>
</tr>
<tr>
<td>adr</td>
<td>vcard</td>
<td> country-name, extended-address, locality, postal-code, post-office-box, street-address,region, type, value </td>
<td>hCard </td>
<td>Address of the object. </td>
</tr>
<tr>
<td>bday </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>The birth date of the object. </td>
</tr>
<tr>
<td>category </td>
<td>vcard, hreview </td>
<td></td>
<td>hCard </td>
<td>Application category of the object.</td>
</tr>
<tr>
<td>class </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>The access classification of the object. For example, public or private. </td>
</tr>
<tr>
<td>country-name </td>
<td>adr, value </td>
<td></td>
<td>hCard </td>
<td>Name of the country for this particular address. </td>
</tr>
<tr>
<td>description</td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>Full text of the description. (Not to be confused with the much longer "summary")</td>
</tr>
<tr>
<td>dtend </td>
<td>vevent </td>
<td></td>
<td>hCalendar </td>
<td>Ending date of the object. </td>
</tr>
<tr>
<td>dtreviewed</td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>Date the review was written, NOT necessarily when the review took place. </td>
</tr>
<tr>
<td>dtstart</td>
<td>vevent </td>
<td></td>
<td>hCalendar </td>
<td>Starting date of the object. (Not to be confused with bday) </td>
</tr>
<tr>
<td>email </td>
<td>vcard, hreview </td>
<td> type, value</td>
<td>hCard </td><td>This object's email address. </td>
</tr>
<tr>
<td>extended-address</td>
<td>adr, value </td>
<td></td>
<td>hCard </td>
<td>Extended address for this particular address.</td>
</tr>
<tr>
<td>fn</td>
<td>vcard, hreview </td>
<td></td>
<td>hCard</td>
<td>The name of the object. </td>
</tr>
<tr>
<td>geo </td>
<td>vcard</td>
<td>latitude, longitude </td>
<td>hCard </td>
<td>Geographical coordinates of the object. </td>
</tr>
<tr>
<td>hreview </td>
<td>*webpage</td>
<td></td>
<td>hReview</td>
<td>A review of some object. </td>
</tr>
<tr>
<td>item </td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>The item that the object exists for. For example, a review about Coca-Cola would list "Coca-Cola" as the item. </td>
</tr>
<tr>
<td>key </td>
<td>vcard</td>
<td>type, value </td>
<td>hCard </td>
<td>Public key of the object</td>
</tr>
<tr>
<td>label </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Formatting to be used by a delivery address label. </td>
</tr>
<tr>
<td>latitude </td>
<td>geo</td>
<td></td>
<td>hCard </td>
<td>The latitude coordinates of the object. </td>
</tr>
<tr>
<td>locality </td>
<td>adr, value </td>
<td></td>
<td>hCard </td>
<td>Locality for this particular address. </td>
</tr>
<tr>
<td>location</td>
<td>vevent </td>
<td></td>
<td>hCalendar </td>
<td>Intended venue of object. (Not to be confused with adr) </td>
</tr>
<tr>
<td>logo </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Object's logo. </td>
</tr>
<tr>
<td>longitude</td>
<td>geo</td>
<td></td>
<td>hCard </td>
<td>The longitude coordinates of the object. </td>
</tr>
<tr>
<td>mailer </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Email software used by the object. </td>
</tr>
<tr>
<td>n </td>
<td>vcard</td>
<td> additional-name, family-name, given-name, honorific-prefix, honorific-suffix, nickname</td>
<td>hCard </td><td>The name of the unit </td>
</tr>
<tr>
<td>note </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Supplemental information about the object. </td>
</tr>
<tr>
<td>org </td>
<td>vcard</td>
<td>organization-name, organization-unit</td>
<td>hCard </td><td>The organization or company of the object. </td>
</tr>
<tr>
<td>organization-name </td>
<td>org</td>
<td></td>
<td>hCard </td><td>The name of the organization or company of the object. </td>
</tr>
<tr>
<td>organization-unit </td>
<td>org</td>
<td></td>
<td>hCard </td><td>The unit or department of the object. </td>
</tr>
<tr>
<td>permalink </td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>A link to the object. This link should never become invalid. Used in <a> </td>
</tr>
<tr>
<td>photo </td>
<td>vcard, hreview </td>
<td></td>
<td>hCard </td>
<td>A photo of the object. Used in <img> </td>
</tr>
<tr>
<td>post-office-box </td>
<td>adr, value </td>
<td></td>
<td>hCard </td>
<td>Post office box number of this particular address. </td>
</tr>
<tr>
<td>postal-code</td>
<td>adr, value</td>
<td></td>
<td>hCard </td>
<td>Postal code for this particular address. </td>
</tr>
<tr>
<td>profile</td>
<td>*webpage</td>
<td></td>
<td>XMDP</td>
<td>Contains metadata types and definitions. Used in <dl> </td>
</tr>
<tr>
<td>rating </td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>Rating of 1-5 or 0-10 of the object. </td>
</tr>
<tr>
<td>region</td>
<td>adr, value </td>
<td></td>
<td>hCard </td>
<td>Region of this particular address. </td>
</tr>
<tr>
<td>rev </td>
<td>vcard</td>
<td></td>
<td>hCard</td>
<td>Specifies revision of the hCard. </td>
</tr>
<tr>
<td>reviewer </td>
<td>hreview</td>
<td>vcard</td>
<td>hReview </td>
<td>Person that wrote the review of the object. </td>
</tr>
<tr>
<td>role </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Information regarding the role of the object. </td>
</tr>
<tr>
<td>sort-string </td>
<td>vcard</td>
<td></td>
<td>hCard </td><td>String used to sort this object in an alphabetical list. </td>
</tr>
<tr>
<td>sound </td>
<td>*any</td>
<td></td>
<td>hCard </td>
<td>Audio reading back another element's content. By default, the "fn". </td>
</tr>
<tr>
<td>street-address </td>
<td>adr, value </td>
<td></td>
<td>hCard</td>
<td>Street address of this particular address. </td>
</tr>
<tr>
<td>summary </td>
<td>vevent , hreview </td>
<td></td>
<td>hCalendar </td>
<td>A short summary or subject for the object. </td>
</tr>
<tr>
<td>tel </td>
<td>vcard</td>
<td> type, value</td>
<td>hCard </td>
<td>Telephone number of the object </td>
</tr>
<tr>
<td>title </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>Job title or functional position of the object.</td>
</tr>
<tr>
<td>type </td>
<td>adr, email, tel </td>
<td></td>
<td>hCard </td>
<td>Defines a type of the parent element. For instance a type of telephone number such as home or work.. Used in conjunction with "value". </td>
</tr>
<tr>
<td>tz </td>
<td>vcard</td>
<td></td>
<td>hCard </td>
<td>The timezone the object is in. </td>
</tr>
<tr>
<td>uid </td>
<td>*any</td>
<td></td>
<td>hCard </td>
<td>Globally unique identifier associated with the object, or one of the object's properties. </td>
</tr>
<tr>
<td>url </td>
<td>vcard, vevent , hreview </td>
<td></td>
<td>hCard </td>
<td>A link to the this object's home page or extended profile. Used in <a> </td>
</tr>
<tr>
<td>value </td>
<td>adr, email, tel </td>
<td></td>
<td>hCard </td>
<td>Used in conjunction with "type". The actual value of a particular type. For instance a telephone number of type work such as +1.415.555.1212. </td>
</tr>
<tr>
<td>vcalendar</td>
<td>*webpage</td>
<td>vevent</td>
<td>hCalendar </td>
<td>A list of calendar events. </td>
</tr>
<tr>
<td>vcard </td>
<td>*webpage, vevent </td>
<td></td>
<td>hCard </td>
<td>Indicates that this element and all containing elements are part of the hCard microformat. </td>
</tr>
<tr>
<td> vevent </td>
<td>*webpage, vcalendar </td>
<td></td>
<td>hCalendar</td>
<td>Indicates that this element and all contained elements are part of the hCalendar format. </td>
</tr>
<tr>
<td>version</td>
<td>hreview</td>
<td></td>
<td>hReview </td>
<td>Version of the format used for the object. </td>
</tr>
<tr>
<td>xoxo </td>
<td>*webpage</td>
<td></td>
<td>XOXO</td>
<td>An outline of data. Used in <ul> and <ol>. </td>
</tr>
</table>

microformats

2005-12-20T20:47:25Z

Atamido: /* more thoughts on how microformats are different */

= microformats =

== What are microformats? ==

=== microformats are ===

* a way of thinking about data
* design principles for formats
* adapted to current behaviors and usage patterns ([http://ifindkarma.typepad.com/relax/2004/12/microformats.html "Pave the cow paths." - Adam Rifkin])
* highly correlated with semantic XHTML, AKA the [http://www.tantek.com/presentations/2004etech/realworldsemanticspres.html real world semantics, AKA lowercase semantic web], AKA [http://www.whump.com/moreLikeThis/link/04069 lossless XHTML]
* described by [http://tantek.com/log/2005/03.html#d13t1722 Tantek's recent presentation at SXSW: The Elements of Meaningful XHTML]
* a set of simple open data format standards that many (including Technorati) are actively developing and implementing for more/better structured blogging and web microcontent publishing in general.
* [http://theryanking.com/blog/archives/2005/04/07/an-evolutionary-revolution/ "An evolutionary revolution" - Ryan King]
* all the above.

=== microformats are not ===

* a new language
* infinitely extensible and open-ended
* an attempt to get everyone to change their behavior and rewrite their tools
* a whole new approach that throws away what already works today
* a panacea for all taxonomies, ontologies, and other such abstractions
* defining the whole world, or even just boiling the ocean
* any of the above

== the microformats principles ==
* solve a specific problem
* start as simple as possible
** solve simpler problems first
** make evolutionary improvements
* design for humans first, machines second
** be presentable ''and'' parsable
** ''visible data'' is much better for humans than ''invisible metadata''
** adapt to current behaviors and usage patterns, e.g. (X)HTML, blogging
** [http://tantek.com/log/2003/0813t1158.html#handauthoring ease of authoring is important]
* reuse building blocks from widely adopted standards
** [http://tantek.com/presentations/20040928sdforumws/semantic-xhtml.html semantic], [http://tantek.com/presentations/2005/03/elementsofxhtml meaningful (X)HTML]. See [[SemanticXHTMLDesignPrinciples]] for more details.
** existing microformats
** well established schemas from interoperable RFCs
* modularity / embeddability
** design to be reused and embedded inside existing formats and microformats
* enable and encourage decentralized and distributed development, content, services
** explicitly encourage the original "spirit of the Web"

== current microformats ==

See the [[Main_Page|main page]] for a list of current microformats specifications, drafts, and discussions.

== more thoughts on how microformats are different ==

There are plenty of existing formats that are ''nearly'' totally useless/ignored.

They're not ''totally'' useless though. They're useful in that they illustrate what at least someone thought might be useful, which unfortunately is typically a lone-inventor working a-priori without any domain expertise.

Or there is the other extreme. Lots of corporate inventors working with plenty of experience, over-designing a format for what ''might'' be needed some day. In particularly bad cases, the corporate vendors collude to prevent openness and/or adoptability by the open source community. Media standards [http://dannyayers.com/archives/2005/09/24/qotd-23/ often suffer from this kind of deliberate "strategic" positioning].

We seek to combat all of those problems with the microformat approach.

* We're not lone-inventors; we're a [http://microformats.org/discuss/ community].
* We don't work [http://en.wikipedia.org/wiki/A_priori a-priori] ("from reason alone"); we require documentation of existing examples, previous attempts at formats. See [[process]].
* When lacking domain expertise, we seek out the domain experts to provide it, and we immerse ourselves in examples and prior art from the domain (see previous point).
* We do our work in the [[Main_Page|open]] with [http://microformats.org/discuss/ open discussion forums].
* We're a diverse mix of corporate, independent, hobbyist, enthusiast.
* We don't over-design. We under-design, deliberately, and then only add things when they are absolutely necessary.
* We adopt very liberal copyright/licensing (CC,GMPG,IETF,W3C) and patent positions (RF,IETF,W3C).
* We ruthlessly self-criticize based on our [http://microformats.org/wiki/microformats#the_microformats_principles principles] in order to keep to the above.

Some ask what the purpose of the (intended) standards is.

Why do you need purpose? More often than not, premature focus on purpose tends to distort data formats towards a particular application which may not be all that relevant. Hence rather than focus on a-priori purpose, we focus on modeling existing behavior, with the knowledge that additional structure will yield plenty of interesting uses, most of which we will not be able to a-priori predict.

This is obviously a very different approach than traditional data format efforts.