Microformats Wiki - User contributions [en]

hreview-issues

2006-02-26T20:34:54Z

PigsOTWing: /* default range */

= hReview issues =

These are externally raised issues about [[hreview|hReview]] 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]] and [[hcard-issues]].

== 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.''

== rel="self" ==

2005-01-04 by [[User:DavidJanes|David Janes]]:

Atom defines rel="self" [http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html#rfc.section.4.2.7 here]

: The value "self" signifies that the IRI in the value of the href attribute identifies a resource equivalent to the containing element.

HTML rel="boomark" [http://www.w3.org/TR/REC-html40/types.html#type-links here]

: Refers to a bookmark. A bookmark is a link to a key entry point within an extended document. The title attribute may be used, for example, to label the bookmark. Note that several bookmarks may be defined in each document.

Since we're using "bookmark" to mean the entry point to the hReview, isn't the "self" redundant or overly subtle?

== default lower bound ==

* YYYY-MM-DD????? raised by [[User:ScottReynen|Scott Reynen]]
*# ''Why is the default lower bound 1 when the [[reviews-formats|real world examples]] almost all have a lower bound of 0?''
*#* REJECTED INVALID ASSUMPTION. Most [[review-examples|real-world examples]] have a lower bound of 1, not 0.

== default range ==
* 2006-02-23 raised by Andy Mabbett
*# ''Not all marks give ratings "out of five". The value should be a percentage. Zero should be allowed.''
*#* REJECTED IGNORES RESEARCH. Most [[review-examples|real-world examples]] have a range of 1.0-5.0 not a percentage. You may set the "best" bound to 100 explicitly, and the "worst" bound to 0 explicitly per the spec if necessary.
*#* "most" != "all"; indeed, the page you cite has examples of "1-10" and "0-100%". I never claimed that many examples use percentages, but I'm sure a mathematician would explain that values in the range "1-5" may be expressed as percentages. Still, I'm sure you know best.

== Specification Clarifications ==

* 2006-02-01 raised by [http://tantek.com Tantek].
*# ''The spec needs to clarify that there is only one "item" per "hreview".''
*#* ACCEPTED. Resolved in hReview 0.3.

hreview-issues

2006-02-23T22:22:21Z

PigsOTWing: /* Ratings */

= hReview issues =

These are externally raised issues about [[hreview|hreview]] 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]] and [[hcard-issues]].

== 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.''

== rel="self" ==

2005-01-04 by [[User:DavidJanes|David Janes]]:

Atom defines rel="self" [http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html#rfc.section.4.2.7 here]

: The value "self" signifies that the IRI in the value of the href attribute identifies a resource equivalent to the containing element.

HTML rel="boomark" [http://www.w3.org/TR/REC-html40/types.html#type-links here]

: Refers to a bookmark. A bookmark is a link to a key entry point within an extended document. The title attribute may be used, for example, to label the bookmark. Note that several bookmarks may be defined in each document.

Since we're using "bookmark" to mean the entry point to the hReview, isn't the "self" redundant or overly subtle?

== default lower bound ==

* YYYY-MM-DD????? raised by [[User:ScottReynen|Scott Reynen]]
*# ''Why is the default lower bound 1 when the [[reviews-formats|real world examples]] almost all have a lower bound of 0?''
*#* REJECTED INVALID ASSUMPTION. Most [[review-examples|real-world examples]] have a lower bound of 1, not 0.

== Specification Clarifications ==

* 2006-02-01 raised by [http://tantek.com Tantek].
*# ''The spec needs to clarify that there is only one "item" per "hreview".''

==Ratings==
2006-02-23 raised by Andy Mabbett

Not all marks give ratings "out of five". The value should be a percentage. Zero should be allowed.

hreview-issues

2006-02-23T22:22:11Z

PigsOTWing: /* Ratings */ attrbution

= hReview issues =

These are externally raised issues about [[hreview|hreview]] 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]] and [[hcard-issues]].

== 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.''

== rel="self" ==

2005-01-04 by [[User:DavidJanes|David Janes]]:

Atom defines rel="self" [http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html#rfc.section.4.2.7 here]

: The value "self" signifies that the IRI in the value of the href attribute identifies a resource equivalent to the containing element.

HTML rel="boomark" [http://www.w3.org/TR/REC-html40/types.html#type-links here]

: Refers to a bookmark. A bookmark is a link to a key entry point within an extended document. The title attribute may be used, for example, to label the bookmark. Note that several bookmarks may be defined in each document.

Since we're using "bookmark" to mean the entry point to the hReview, isn't the "self" redundant or overly subtle?

== default lower bound ==

* YYYY-MM-DD????? raised by [[User:ScottReynen|Scott Reynen]]
*# ''Why is the default lower bound 1 when the [[reviews-formats|real world examples]] almost all have a lower bound of 0?''
*#* REJECTED INVALID ASSUMPTION. Most [[review-examples|real-world examples]] have a lower bound of 1, not 0.

== Specification Clarifications ==

* 2006-02-01 raised by [http://tantek.com Tantek].
*# ''The spec needs to clarify that there is only one "item" per "hreview".''

==Ratings==
2006-02-23 raised by Andy Mabbett
Not all marks give ratings "out of five". The value should be a percentage. Zero should be allowed.

hreview-issues

2006-02-23T22:21:42Z

PigsOTWing: /* Ratings */ Zero should be allowed.

= hReview issues =

These are externally raised issues about [[hreview|hreview]] 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]] and [[hcard-issues]].

== 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.''

== rel="self" ==

2005-01-04 by [[User:DavidJanes|David Janes]]:

Atom defines rel="self" [http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html#rfc.section.4.2.7 here]

: The value "self" signifies that the IRI in the value of the href attribute identifies a resource equivalent to the containing element.

HTML rel="boomark" [http://www.w3.org/TR/REC-html40/types.html#type-links here]

: Refers to a bookmark. A bookmark is a link to a key entry point within an extended document. The title attribute may be used, for example, to label the bookmark. Note that several bookmarks may be defined in each document.

Since we're using "bookmark" to mean the entry point to the hReview, isn't the "self" redundant or overly subtle?

== default lower bound ==

* YYYY-MM-DD????? raised by [[User:ScottReynen|Scott Reynen]]
*# ''Why is the default lower bound 1 when the [[reviews-formats|real world examples]] almost all have a lower bound of 0?''
*#* REJECTED INVALID ASSUMPTION. Most [[review-examples|real-world examples]] have a lower bound of 1, not 0.

== Specification Clarifications ==

* 2006-02-01 raised by [http://tantek.com Tantek].
*# ''The spec needs to clarify that there is only one "item" per "hreview".''

==Ratings==
Not all marks give ratings "out of five". The value should be a percentage. Zero should be allowed.

hreview-issues

2006-02-23T22:18:45Z

PigsOTWing: Ratings

= hReview issues =

These are externally raised issues about [[hreview|hreview]] 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]] and [[hcard-issues]].

== 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.''

== rel="self" ==

2005-01-04 by [[User:DavidJanes|David Janes]]:

Atom defines rel="self" [http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html#rfc.section.4.2.7 here]

: The value "self" signifies that the IRI in the value of the href attribute identifies a resource equivalent to the containing element.

HTML rel="boomark" [http://www.w3.org/TR/REC-html40/types.html#type-links here]

: Refers to a bookmark. A bookmark is a link to a key entry point within an extended document. The title attribute may be used, for example, to label the bookmark. Note that several bookmarks may be defined in each document.

Since we're using "bookmark" to mean the entry point to the hReview, isn't the "self" redundant or overly subtle?

== default lower bound ==

* YYYY-MM-DD????? raised by [[User:ScottReynen|Scott Reynen]]
*# ''Why is the default lower bound 1 when the [[reviews-formats|real world examples]] almost all have a lower bound of 0?''
*#* REJECTED INVALID ASSUMPTION. Most [[review-examples|real-world examples]] have a lower bound of 1, not 0.

== Specification Clarifications ==

* 2006-02-01 raised by [http://tantek.com Tantek].
*# ''The spec needs to clarify that there is only one "item" per "hreview".''

==Ratings==
Not all marks give ratings "out of five". The value should be a percentage.

hreview

2006-02-23T22:17:12Z

PigsOTWing: clarifications

<h1> hReview 0.3 </h1>

[[hreview|hReview]] is a simple, open, distributed format, suitable for embedding reviews (of products, servcies, entertainments, etc.) in (X)HTML, Atom, RSS, and arbitrary XML. hReview is one of several [[microformats]] open standards.

Want to get started with writing an [[hreview|hReview]]? Use the [http://microformats.org/code/hreview/creator hReview creator] to write a review and publish it.

== Microformats Draft Specification 2006-02-22 ==

; Editor: [http://tantek.com/ Tantek Çelik], [http://technorati.com Technorati, Inc.]
; Authors: [http://tantek.com/ Tantek Çelik], [http://technorati.com Technorati, Inc.]
: [http://360.yahoo.com/alidiabali Ali Diab],[http://yahoo.com Yahoo! Inc.]
: [http://spaces.msn.com/members/ianmcallister/ Ian McAllister], [http://microsoft.com/ Microsoft Corporation]
: [http://journals.aol.com/panzerjohn/abstractioneer John Panzer], [http://www.aol.com America Online, Inc.]
: [http://ifindkarma.com/blog Adam Rifkin], [http://labs.commerce.net/ CommerceNet Labs]
: [http://sippey.typepad.com/ Michael Sippey], [http://sixapart.com Six Apart, Ltd.]

Microformats [http://microformats.org/wiki/hreview#Copyright copyright] and [http://microformats.org/wiki/hreview#Patents patents] statements apply.

__TOC__

== Introduction ==
Numerous web sites publish reviews using a broad variety of schema for all sorts of things from products (movies, music, books), to businesses (restaurants, hotels, stores), to events (concerts, theatre), to people (artists, leaders, celebrities), to places (landmarks, parks), to online resources (web pages, files), to reviews of reviews themselves.

In order to enable and encourage the sharing, distribution, syndication, and aggregation, of reviews, the authors propose the hReview microformat, an open standard for distributed reviews. The authors have researched both numerous [[review-examples]] in the wild and earlier attempts at [[review-formats]], and have designed hReview around a simple minimal schema for reviews. Feedback is encouraged on the [[hreview-feedback|hReview feedback]] page.

=== Inspiration and Acknowledgments ===
Thanks to everyone who responded to the open call for implementor participation for hReview. The authors in particular wish to thank the following individuals for their constructive input and feedback: [http://www.richardault.com/ Richard Ault], [http://dannyayers.com Danny Ayers], [http://www.vertexdev.com/~jeff/ Jeffrey Barr],[http://adriancuthbert.blogspot.com/ Adrian Cuthbert],[http://jason.defillippo.com/ Jason DeFillippo], [http://www.hybernaut.com/bdv Brian Del Vecchio], Scott Derringer, [http://budgibson.com/home/ Bud Gibson], [http://joi.ito.com/ Joi Ito], [http://www.kanai.net/weblog/ Gen Kanai],[http://niallkennedy.com/ Niall Kennedy], [http://labs.commerce.net/wiki/index.php/Rohit_Khare Rohit Khare], [http://theryanking.com/ Ryan King], [http://www.jluster.org/ Jonas Luster], [http://epeus.blogspot.com/ Kevin Marks], Mark Nottingham, [http://www.powazek.com/ Derek Powazek], [http://www.judysbook.com/ Jeff Rodenburg], [http://sifry.com/alerts/ David Sifry], [http://jystewart.net/ James Stewart], [http://kung-foo.tv/ Adriaan Tijsseling], [http://www.flashenabled.com/ Phillip Torrone], Thai Tran, [http://w6daily.winn.com/ Phillip Winn], [http://yohei-y.blogspot.com YAMAMOTO Yohei].

=== Scope ===
Reviews consistently share several common fields. Where possible hReview has been based on this minimal common subset.

==== Out of scope ====
Fields that are type-specific have been omitted from hReview. It is important that hReview be kept simple and minimal from the start. Additional features can be added as deemed necessary by practical implementation experience.

The concept of a "universal object identifier", that is, how to identify the same object/item/product across different shopping sites, though something very useful to have, is outside the scope of this format.

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

== Format ==
=== In General ===
The hReview format is based on a set of fields common to numerous review sites and formats in use today on the web. Where possible field names have been chosen based on those defined by the related [[hcard|hCard]] and [[hcalendar|hCalendar]] standards.

=== Schema ===
The hReview schema consists of the following:

* hReview ('''<code>hreview</code>''')
** '''<code>version</code>'''. optional. text.
** '''<code>summary</code>'''. optional. text.
** item '''<code>type</code>'''. optional. product | business | event | person | place | website | url.
** '''<code>item</code>''' info. required. ('''<code>fn</code>''' || '''<code>url</code>''' || '''<code>photo</code>''' ) | '''[[hcard|hCard]]''' (for person or business) | '''[[hcalendar|hCalendar]]''' (for event)
** '''<code>reviewer</code>'''. optional. '''[[hcard|hCard]]'''.
** '''<code>dtreviewed</code>'''. required. ISO8601 absolute date time.
** '''<code>rating</code>'''. optional. fixed point integer [1.0-5.0], with optional alternate '''<code>worst</code>''' (default:1.0) and/or '''<code>best</code>''' (default:5.0), also fixed point integers, and explicit '''<code>value</code>'''.
** '''<code>description</code>'''. optional. text with optional valid XHTML markup.
** tags. optional. keywords or phrases, using '''[[rel-tag]]''', each with optional rating.
** permalink. optional, using '''[[rel-bookmark]]''' and '''[[rel-self]]'''.
** license. optional, using '''[[rel-license]]'''.

=== Field details ===
The fields of the hReview schema represent the following:

'''version''':: This optional field permits hReview publishers to specify a particular version of hReview that their content uses. By omitting this field, the publisher is stating that implementations may interpret the hReviews according to any version of the hReview specification v0.2 or later. In practice the authors of this specification are comitted to maintaining backward compatibility with content produced using earlier versions of the specification. This field is syntax compatible with, and thus reuses the semantics of "VERSION" as defined in vCard RFC2426 section "3.6.9 VERSION Type Definition". The value of this field for this specification is "0.2".

'''summary''':: This optional field serves as a title for the review itself.

'''item type''':: This optional field "type" provides the type of the item being reviewed, one of the following: product, business, event, person, place, website, url. If omitted, then in some cases the item type may be inferred. If the item is also an [[hcard|hCard]], then the item type is a "business" or a "person" based upon which of those the hCard represents. If the item is also an [[hcalendar|hCalendar]] event, then the item type is an "event".

'''item info''':: This required field MUST have at a minimum the name ("fn" - the formatted text corresponding to the name) of the item , SHOULD provide at least one URI ("url") for the item, and MAY provide at least one URL to a photo or depiction ("photo") of the item. For items of type person or business, the item info (fn, url, photo) MUST be encapsulated in an [[hcard|hCard]]. For items of type event, the item info SHOULD be encapsulated in an [[hcalendar|hCalendar]] "vevent". Unique item IDs (e.g. ISBNs, UPCs) MAY be represented as a URN ("url") for the item.

'''reviewer''':: The optional field specifies the person who authored the review. If the reviewer is specified, an hCard representing the reviewer MUST be provided. For anonymous reviews, use "anonymous" (without quotes) for the full name of the reviewer. If no "reviewer" is found inside the hReview, parsers should look outside the hReview, in the context of the page, for the "reviewer". If there is no "reviewer" outside either, then parsers should use the author defined by the containing document language, e.g. for (X)HTML documents, the <code><nowiki><address></nowiki></code> contact info for the page (which is ideally marked up as an [[hcard|hCard]] as well), for Atom 1.0 the <code><nowiki><entry></nowiki></code> <code><nowiki><author></nowiki></code> if present and if not the <code><nowiki><feed></nowiki></code> <code><nowiki><author></nowiki></code>, for RSS the <code><nowiki><author></nowiki></code> inside the containing <code><nowiki><item></nowiki></code> element.

'''dtreviewed''':: This required field MUST provide an ISO8601 absolute date time of when the review was written or otherwise authored. This field SHOULD use UTC, but MAY use the time zone offset syntax.

'''rating''':: The rating is a fixed point integer (one decimal point of precision) from 1.0 to 5.0 inclusive indicating a rating for the item, higher indicating a better rating by default. Optionally a different integral "worst" value and/or "best" value MAY be specified (e.g. 6 from 0-10). The "best" value may be numerically smaller than the "worst" value.

'''description''':: This optional field contains the full text representing the written opinion of the reviewer. The field MAY include valid XHTML markup (e.g. paragraphs). User agents SHOULD preserve any markup. Multiple descriptions or section descriptions (e.g. pros and cons, plusses and minusses) SHOULD be included in the description field.

'''tags''':: Tags are represented using a list of keywords or phrases (using the [[rel-tag]] microformat for each individual keyword or phrase tag) that the reviewer associates with the item. The reviewer MAY optionally provide a tag-specific rating inside each [[rel-tag]], e.g. ambience:5. Tag-specific ratings by default use the same range as an overall rating for the item if present, and MAY also have a custom worst...best range specified. Authors MAY also invert this structure for the same semantic if it is more convenient for their markup, that is, place the [[rel-tag]] inside a rating to indicate a rated tag. Note: rated tags should ideally use a tag space that explains what the ratings for that tag mean. E.g. Food:18/30 should link to a tags space for Food that explains what an 18 out of 30 means for the Food tag.

'''permalink''':: This optional field is a URL for the hReview. In addition to using the <code><a href></code> tag for this field, the attribute <code>rel="self bookmark"</code> MUST be used to indicate that the hyperlink is a permalink for the review itself. If the hyperlink already contains a <code>rel</code> attribute, then the values <code>self</code> and <code>bookmark</code> MUST be included among the space-separated set of values in the attribute. Indexers MAY treat the permalink of a review as a unique ID in order to identify and collate the same review from multiple sources (such as indexing a page multiple times). The permalink MAY also be used to indicate or imply the origin of the review. Authors MAY use the classname of "permalink" on the element representing the permalink, but are not required to do so.

The following field names have been reused from the [[hcard|hCard]] and [[hcalendar|hCalendar]] microformats: <code>version, summary, fn, url, email, photo, description, categories</code>. In addition, items and reviewers described by hCards MAY contain any hCard field. The rel value "self" has been reused from the [http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html Atom 1.0 specification].

'''license''':: This optional field links to the license under which the contents of the hReview itself is licensed, using the '''[[rel-license]]''' microformat.

=== More Semantic Equivalents ===

For some properties there is a more semantic equivalent, and therefore they get special treatment, e.g.:

* For any "url", use <code><a class="url" href="...">...</a></code> inside the element with the class name 'hreview' in hReview.
* Similarly, any "email", use <code><nowiki><a class="email" href="mailto:...">...</a></nowiki></code>
* And for "photo", use <code><img class="photo" src="..." alt="Photo of ..." /></code>

* Ratings are often presented either as a set of images or characters, e.g. "***". For these, the <code><abbr></code> element is particularly useful, as such characters are an abbreviation for the precise rating, e.g. <code><abbr class="rating" title="3">***</abbr></code>. This is further explored in the next section.

==== Language ====
* To explicitly convey the natural language that an hReview is written in, use the standard (X)HTML 'lang' attribute on the element with class="hreview", e.g. <code><div class="hreview" lang="en"> ... </div></code> If portions of an hReview (e.g. the item name) are in a different language, use the 'lang' attribute on those portions.
* hReview processors which need to handle the language of reviews MUST process the standard (X)HTML 'lang' attribute as specified.

=== Human vs. Machine Readable ===
If an <code><abbr></code> element is used for a property, then its '<code>title</code>' attribute is used for the value of the property, instead of the contents of the element, which can then be used to provide a user-friendly alternate presentation 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.

=== Object Includes ===

hReview 0.3 includes support for the object [[include-pattern]].

Often a single page lists an item, and then several reviews for that item. In order to avoid having to repeat the item info for each review of the item, the first review should be marked up as an hReview, with a unique "id" attribute on the item info, and then following reviews should use the object [[include-pattern]] to include the item info from the first review.

=== Notes ===
This section is informative.

* By marking up a review with the hReview microformat, the expectation is communicated that the review MAY be indexed. This has no impact on the copyright of the review itself which the publisher may explicitly specify using [[rel-license]] as specified above.
* The enumerated list of item types is under development and may be extended.
* Each type may have custom hReview fields that follow the common set.
* Additional details about a particular item should be specified with the rest of the item's info at the URL provided for the item.
* Most rating systems use the range 1.0 to 5.0, and most of those represent the rating as a number (and possibly half) of stars. Sites may use whatever graphic they wish to represent the rating.

== Examples ==
Here are a few examples of reviews from current web sites, and how they could be easily enhanced to support the hReview structured review microformat.

Want to get started with writing an [[hreview|hReview]]? Use the [http://microformats.org/code/hreview/creator hReview creator] to write a review and publish it on your blog.

=== Restaurant reviews ===

Here is an example of a simple online restaurant review:

<pre><nowiki>
<div>
5 stars out of 5 stars
<h4>Crepes on Cole is awesome</h4>
Reviewer: Tantek - April 18, 2005
<blockquote>
Crepes on Cole is one of the best little creperies in San Francisco.
Excellent food and service. Plenty of tables in a variety of sizes
for parties large and small. Window seating makes for excellent
people watching to/from the N-Judah which stops right outside.
I've had many fun social gatherings here, as well as gotten
plenty of work done thanks to neighborhood WiFi.
</blockquote>
Visit date: April 2005
Food eaten: Florentine crepe
</div>
</nowiki></pre>

Adding hReview to this review is quite simple:

<pre><nowiki>
<div class="hreview">
5 out of 5 stars
<h4 class="summary">Crepes on Cole is awesome</h4>
Reviewer: Tantek -
<abbr class="dtreviewed" title="20050418T2300-0700">April 18, 2005</abbr>
<div class="description item vcard">
Crepes on Cole is one of the best little
creperies in San Francisco.
Excellent food and service. Plenty of tables in a variety of sizes
for parties large and small. Window seating makes for excellent
people watching to/from the N-Judah which stops right outside.
I've had many fun social gatherings here, as well as gotten
plenty of work done thanks to neighborhood WiFi.
</div>
Visit date: April 2005
Food eaten: Florentine crepe
</div>
</nowiki></pre>

Note that some of the properties of this sample review are not captured by hReview (visit date, food eaten). This is deliberate per the scope of keeping hReview minimal and simple.

This sample hReview could be rendered like this:

5 stars out of 5 stars 
'''Crepes on Cole is awesome''' 
Reviewer: Tantek - April 18, 2005 

Crepes on Cole is one of the best little creperies in San Francisco. Excellent food and service. Plenty of tables in a variety of sizes for parties large and small. Window seating makes for excellent people watching to/from the N-Judah which stops right outside. I've had many fun social gatherings here, as well as gotten plenty of work done thanks to neighborhood wifi.

Visit date: April 2005 
Food eaten: Florentine crepe 

==== Multidimensional Restaurant Review ====
Some restaurant reviews indicate ratings for different aspects of the restaurant. Such details are represented in hReview using tagged ratings. In addition, note the inline tags inside the description of this review.

Here is one such review in text format:

Cafe Borrone

1010 El Camino Real, Menlo Park, CA 94025, +1-650-327-0830;
cafeborrone.com

Food: 18/30; Ambience: 19/30; Service: 15/30; Price: $$...

This cafe is a welcoming oasis on the Peninsula. It even has a fountain
outside which cloaks the nearby sounds of El Camino traffic. Next door to a
superb indy bookstore, Cafe Borrone is an ideal spot to grab a coffee or a
snack to accompany a newly purchased book or imported periodical. Soups and
sandwich specials rotate daily. The corn chowder with croutons and big
chunks of cheese goes especially well with a freshly toasted mini-baguette.
Evenings are often crowded and may require sharing a table with a perfect
stranger. Espresso afficionados will appreciate the Illy coffee. Noise
levels can vary from peaceful in the late mornings to nearly overwhelming on
jazz band nights.

As an hReview:

<pre><nowiki>
<div class="hreview">
<div class="item vcard">
<div class="fn org summary">Cafe Borrone</div>

1010 El Camino Real,
Menlo Park,
CA
94025,

+1-650-327-0830;
<a class="url" href="http://cafeborrone.com">cafeborrone.com</a>
</div>
<ul class="categories">
<li class="rating"><a href="http://en.wikipedia.org/wiki/Food" rel="tag">
Food: 18/30</a>;</li>
<li class="rating"><a href="http://flickr.com/photos/tags/Ambience" rel="tag">
Ambience: 19/30</a>;</li>
<li class="rating"><a href="http://en.wikipedia.org/wiki/Service" rel="tag">
Service: 15/30</a>;</li>
<li class="rating"><a href="http://en.wikipedia.org/wiki/Price" rel="tag">
Price: <abbr class="value" title="2">$$</abbr>...</a></li>
</ul>
<div class="description">
This <abbr class="type" title="business">
<a href="http://en.wikipedia.org/wiki/cafe" rel="tag">cafe</a></abbr>
is a welcoming oasis on the Peninsula.
It even has a fountain outside which nearly eliminates
the sounds of El Camino traffic. Next door to a superb indy bookstore,
Cafe Borrone is an ideal spot to grab a
<a href="http://en.wikipedia.org/wiki/coffee" rel="tag">coffee</a>
or a meal to accompany a newly purchased book or imported periodical.
<a href="http://technorati.com/tag/soup" rel="tag">Soups</a> and
<a href="http://technorati.com/tag/sandwich" rel="tag">sandwich</a>
specials rotate daily. The corn chowder with croutons and big chunks of cheese
goes especially well with a freshly toasted mini-baguette. Evenings are
often crowded and may require sharing a table with a perfect stranger.
<a href="http://flickr.com/photos/tags/espresso" rel="tag">Espresso</a>
afficionados will appreciate the
<a href="http://en.wikipedia.org/wiki/Illy" rel="tag">Illy</a> coffee.
Noise levels can vary from peaceful in the late mornings to nearly overwhelming on
<a href="http://en.wikipedia.org/wiki/jazz" rel="tag">jazz</a> band nights.
</div>
Review (<a href="http://microformats.org/wiki/hreview">
hReview v0.3</a>)
by anonymous,
<abbr class="dtreviewed" title="20050428T2130-0700">April 28th, 2005</abbr>.
</div>
</nowiki></pre>

With an accompanying CSS style sheet like:

<pre><nowiki>
a.url { display:block }
ul.categories { margin:1em 0; padding:0 }
.categories li { display:inline }
</nowiki></pre>

This hReview could be presented similar to the original text:

Cafe Borrone 
1010 El Camino Real, Menlo Park, CA 94025, +1-650-327-0830; 
[http://cafeborrone.com/ cafeborrone.com] 
 
[http://en.wikipedia.org/wiki/Food Food: 18/30];
[http://flickr.com/photos/tags/Ambience Ambience: 19/30];
[http://en.wikipedia.org/wiki/Service Service: 15/30];
[http://en.wikipedia.org/wiki/Price Price: $$...] 

This [http://en.wikipedia.org/wiki/cafe cafe] is a welcoming oasis on the Peninsula. It even has a fountain outside which cloaks the nearby sounds of El Camino traffic. Next door to a superb indy bookstore, Cafe Borrone is an ideal spot to grab a [http://en.wikipedia.org/wiki/coffee coffee] or a snack to accompany a newly purchased book or imported periodical. [http://technorati.com/tag/soup Soups] and [http://technorati.com/tag/sandwich sandwich] specials rotate daily. The corn chowder with croutons and big chunks of cheese goes especially well with a freshly toasted mini-baguette. Evenings are often crowded and may require sharing a table with a perfect stranger. [http://flickr.com/photos/tags/espresso Espresso] afficionados will appreciate the [http://en.wikipedia.org/wiki/Illy Illy] coffee. Noise levels can vary from peaceful in the late mornings to nearly overwhelming on [http://en.wikipedia.org/wiki/jazz jazz] band nights.

Review ([http://microformats.org/wiki/hreview hReview v0.3]) by anonymous, April 28th, 2005.

=== Product review ===
Here is an example of a product review:

<pre><nowiki>
<div>
<a href="http://www.amazon.com/exec/obidos/ASIN/B000089CJI/">
<img src="http://images.amazon.com/images/P/B000089CJI.01._SCTHUMBZZZ_.jpg"
alt="Album cover photo: The Postal Service: Give Up." />
The Postal Service: Give Up</a>
<blockquote>
"The people thought they were just being rewarded for treating others
as they like to be treated, for obeying stop signs and curing diseases,
for mailing letters with the address of the sender... Don't wake me,
I plan on sleeping in..."

"Nothing Better" is a great track on this album, too...
</blockquote>
(*****)
</div>
</nowiki></pre>

Adding hReview to this review is also quite simple, but in this case requires a few more elements for the rating and reviewer which are required by hReview:

<pre><nowiki>
<div class="hreview">
<a class="item url" href="http://www.amazon.com/exec/obidos/ASIN/B000089CJI/">
<img src="http://images.amazon.com/images/P/B000089CJI.01._SCTHUMBZZZ_.jpg"
alt="Album cover photo: The Postal Service: Give Up. "
class="photo" />
The Postal Service: Give Up</a>
<div class="description">
"The people thought they were just being rewarded for treating others
as they like to be treated, for obeying stop signs and curing diseases,
for mailing letters with the address of the sender... Don't wake me,
I plan on sleeping in..."

"Nothing Better" is a great track on this album, too...
</div>
(<abbr class="rating" title="5">*****</abbr>)
Review by
<a class="url fn" href="http://ifindkarma.com/blog/">Adam Rifkin</a>,
<abbr class="dtreviewed" title="200502">February 2005</abbr>

</div>
</nowiki></pre>

And this hReview might be presented like this:

[Album cover photo: ]
[The Postal Service:]
[ Give Up ]

The Postal Service: Give Up

"The people thought they were just being rewarded for treating others as they like to be treated, for obeying stop signs and curing diseases, for mailing letters with the address of the sender... Don't wake me, I plan on sleeping in..."

"Nothing Better" is a great track on this album, too...

(*****)

Review by Adam Rifkin, February 2005.

=== Movie Review ===
Finally, here is an example of a movie review.

<pre><nowiki>
<div>
anonymous, April 18th, 2005
<div>
<a lang="zh" href="http://www.imdb.com/title/tt0299977/">
Ying Xiong (HERO)
</a>
</div>
<div>Rating: 4 out of 5</div>
<blockquote>
This movie has great visuals and music.
</blockquote>
</div>
</nowiki></pre>

With hReview:

<pre><nowiki>
<div class="hreview">

anonymous,
<abbr class="dtreviewed" title="20050418">April 18th, 2005</abbr>

<div class="item">
<a lang="zh" class="url fn" href="http://www.imdb.com/title/tt0299977/">
Ying Xiong (HERO)
</a>
</div>
<div>Rating: 4 out of 5</div>
<div class="description">
This movie has great music and visuals.
</div>
</div>
</nowiki></pre>

Which could be presented like this:

anonymous, April 18th, 2005 
Ying Xiong (HERO) 
Rating: 4 out of 5 

This movie has great music and visuals.

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

The following sites have published hReviews, and thus are a great place to start for anyone looking for examples "in the wild" to try parsing, indexing, organizing etc. If you publish hReviews 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.

Want to get started with writing an [[hreview|hReview]]? Use the [http://microformats.org/code/hreview/creator hReview creator] to write a review and publish it on your blog.

*[http://jg.typepad.com/ciel/ Joan] has published [http://jg.typepad.com/ciel/2006/02/daniel_bouluds_.html an hReview of Garçon]
*[http://zipingo.typepad.com/ Zipingo Team Blog], a collaborative blog by the Zipingo Product Development Team at Intuit, used the hReview format to tag [http://zipingo.typepad.com/my_weblog/2005/12/finding_an_elec.html the backstory] of a review on a San Mateo electrician, written by one of the Zipingo team members ZipingoJim. Jim's post also links to his review on [http://www.zipingo.com Zipingo], a consumer opinion site.
* [http://mincedmedia.blogspot.com/ Minced Media], a media blog by author/writer [http://www.kimbayne.com Kim M. Bayne], used the hReview format to tag her rant about [http://mincedmedia.blogspot.com/2005/09/old-yeller.html customer service]. Future reviews of business and media will contain hReview.
* [http://ukfilmreview.blogspot.com/ UK Film Review] a new blog using hReview format to review Films and DVD releases in the UK
* [http://www.debaser.it/ DeBaser.it] publishes music reviews (in Italian) supporting hReview.
* [http://blog.ftwr.co.uk/ Peter Westwood] posted an [http://blog.ftwr.co.uk/archives/2006/01/05/the-fox-inn/ hReview of The Fox Inn]
* [http://www.livejournal.com/users/danieljohn/ Daniel John] provides a [http://www.livejournal.com/users/danieljohn/58674.html scathing hReview of CIBC].
* [http://uk.movies.yahoo.com/movie-reviews/ Yahoo UK Movie Reviews] now supports hReview on all (>2000) reviews, e.g. [http://uk.movies.yahoo.com/h/Harry-Potter-and-the-Goblet-of-Fire/review-41195.html Harry Potter and the Goblet of Fire Review]
* [http://adam.typepad.com/impossiblethings/ Adam Hertz] wrote an [http://adam.typepad.com/impossiblethings/2005/11/soluna.html hReview of Soluna]
* [http://www.mattmcalister.com/blog/ Matt McAllister] wrote an [http://www.mattmcalister.com/blog/_archives/2005/11/16/1408893.html hReview of the TV show: "The Office"]
* [http://www.bmannconsulting.com/blog/bmann/ Boris Mann] wrote an [http://www.bmannconsulting.com/blog/bmann/doubletake-best-panorama-stitch-tool-for-mac-os-x hReview of DoubleTake, a panorama stitch tool for Mac OS X]
* [http://blog.ftwr.co.uk/ Peter Westwood] has written an [http://blog.ftwr.co.uk/archives/2005/10/03/blubeckers-hampton-court/ hReview of Blubeckers Hampton Court] and an [http://blog.ftwr.co.uk/archives/2006/01/05/the-fox-inn/ hReview of The Fox Inn Bucks Green, West Sussex]
* [http://dougal.gunters.org/blog/ Dougal] has published an [http://dougal.gunters.org/blog/2005/08/03/french-vanilla-latte hReview of Wolfgang Puck’s Gourmet French Vanilla Latte].
* [http://www.dinnerbuzz.com/ Dinnerbuzz] is a great site for posting tagged reviews of restaurants, and they publish and summarize all their reviews in hReview!
* [http://soldierant.net/ Bryce Glass] posted an [http://soldierant.net/archives/2005/06/product_review.html hReview of the Uniden ELBT 595 Bluetooth Cordless Phone].
* dda posted an [http://sungnyemun.org/wordpress/?p=20 hReview of hReview] :)
* An [http://tbp.xomerang.com/?p=3 hReview of Caffè Camardo coffee].
* [http://loadaveragezero.com/hnav/contact.php Douglas Clifton] posted [http://loadaveragezero.com/#May-12-2005 comments] regarding adapting his list of ~800 [http://loadaveragezero.com/app/drx Developer Resources] as a format for evaluating hReview.
* [http://www.oliverbrown.me.uk/ Oliver Brown] [http://www.oliverbrown.me.uk/2005/05/09/sitereviewsorg-supports-hreview-i-think/ has announced] that his [http://en-us.sitereviews.org/ SiteReviews.org] (which reviews websites) publishes its reviews using hReview, e.g. here is the [http://en-us.sitereviews.org/review-photomatt.net review on SiteReviews.org for photomatt.net].
* [http://www.myelin.co.nz/post/ Phillip Pearson] is publishing hReviews in the [http://coffee.gen.nz/rss/reviews RSS feed of cafe reviews] on his [http://coffee.gen.nz/ kiwi coffee review site], which of course has the reviews in HTML with embedded hReview markup as well.
* [http://station11.net/ticker/ Kjell] is publishing his link blog as a [http://station11.net/ticker/ list of hReviews].
* [http://epeus.blogspot.com/ Kevin Marks] has [http://epeus.blogspot.com/2005_04_01_epeus_archive.html#111484565269684374 published two hReviews] and used unicode "star" characters for his ratings!
* JamesStewart is publishing hReviews in the location pages at his [http://grwifi.net Grand Rapids WiFi site].
* [http://soldierant.net/ Soldier Ant] has [http://soldierant.net/archives/2005/06/product_review.html reviewed a cordless phone].
* [http://www.happenchance.co.uk/ Paul Livingstone] uses hreview to voice his opinion on [http://www.happenchance.co.uk/archives/2005/07/war_of_the_worl.php books], [http://www.happenchance.co.uk/archives/2005/03/im_going_to_fin.php movies] and [http://www.happenchance.co.uk/archives/2005/05/eels_carling_ac.php music].
* [http://www.stuffandnonsense.co.uk/ Andy Clarke] uses hReview for his [http://www.stuffandnonsense.co.uk/general/recommended-reading.html recommended reading list]
* [http://www.tjameswhite.com/blog Tim White] has begun implementing hReviews at [http://reviews.gale.com at work].
* [http://nachlin.com/ Jim Nachlin] has added hReview publishing to the CMS he uses to publish [http://daysofleisure.com/writing his blog].
* [http://whumpdotcom.livejournal.com/236856.html Bill Humphries] has reviewed the book "A Brother's Price" on his LiveJournal.

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

The following implementations have been developed which either generate or parse hReviews. If you have an hReview 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.

* [http://www.reevoo.com/blogs/bengriffiths/ Revieworld CTO Ben Griffiths] has announced that they have built support into [http://www.reevoo.com/ Reevoo] to [http://www.reevoo.com/blogs/bengriffiths/2006/02/01/join-the-reevolution/ aggregate reviews of products that are published on blogs using hReview]
* [http://brain.lionsden.com/ Leo Cerebellum Annotare] notes that [http://brain.lionsden.com/?p=229 ReviewZilla Alpha 2 includes MicroFormat hReview markup]
* [http://blog.codeeg.com/ Calvin Yu] has written a [http://blog.codeeg.com/2006/01/28/using-microformats-to-plot-my-favorite-places/ web service that will allow you plot and describe places on a Yahoo Map easily] using [[hreview|hReview]] and [[geo]].
* [http://blog.codeeg.com/tails-firefox-extension/ Tails is a Firefox Extension] that will display the presence of microformats ([[hcard|hCard]], [[hcalendar|hCalendar]], [[hreview|hReview]], [[xfolk|xFolk]]) on a webpage.
* [http://kritx.com Kritx] is a site that indexes hReviews and other reviews on the Web.
* [http://www.goodpic.com/mt/aws/index_us.html Goodpic] has written:
** [http://www.goodpic.com/mt/aws/index_us.html hReview creator for Amazon.com products]
** [http://www.goodpic.com/mt/aws/index_uk.html hReview creator for Amazon.co.uk products]
** [http://www.goodpic.com/mt/aws/index_uk.html hReview creator for Amazon.co.jp products]
** be sure to choose the "hRview" tab from among the choices on the page that says "You can choose from more than 30 designs, please click the tab to select categories."
* See the microformats.org [http://microformats.org/code/hreview/creator hReview creator]
* [http://www.eigaseikatu.com/ Eigaseikatu], one of the largest movie community sites in Japan, provides [http://www.eigaseikatu.com/hreview/ hReview creator] for movie review.
* [http://sungnyemun.org/wordpress/?p=22 hReview plugin for WordPress]
* [http://theryanking.com/ Ryan King] has an [http://theryanking.com/microformats/hreview-creator.html hReview Creator].
* [http://rvu.ning.com/ Rvu] is a [http://ning.com Ning] app that lets you write reviews of reviews and publishes them in hReview

== References ==
=== Normative References ===
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]
* [http://gmpg.org/xmdp/ XMDP]
* [[hcard|hCard]]
* [[hcalendar|hCalendar]]
* [[rel-tag]]
* [http://www.ietf.org/rfc/rfc2119.txt RFC2119]
* [http://www.ietf.org/rfc/rfc3986.txt RFC3986]
* [http://www.ietf.org/rfc/rfc4287.txt RFC4287] (Atom 1.0)

=== Informative References ===
* [http://www.w3.org/TR/REC-CSS1 CSS1]
* ISO.8601.1988
** International Organization for Standardization, "Data elements and interchange formats - Information interchange - Representation of dates and times", ISO Standard 8601, June 1988.
* [http://www.w3.org/TR/1998/NOTE-datetime-19980827 W3C NOTE-datetime-19980827]
* [http://www.ietf.org/rfc/rfc3667.txt RFC3667]
* [http://www.ietf.org/rfc/rfc3668.txt RFC3668]
* [http://www.w3.org/Consortium/Patent-Policy-20040205/ W3C Patent Policy]
* Other reviews efforts. See [[reviews-formats]].
* Contributed from http://developers.technorati.com/wiki/hReview.

==== Similar Work ====
* [[hlisting-proposal|hListing]]
* [[xoxo|XOXO]]

=== Copyright ===
{{MicroformatCopyrightStatement2005}}

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

== Work in progress ==
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added.

=== Changes from v0.2 ===
The following changes have been made in hReview v0.3 over [[hreview-v0.2|hReview v0.2]]:

Normative changes:
# MUST (instead of SHOULD) use [[hcard|hCard]] for the item description of a business or person
# "reviewer" changes
## Made reviewer *optional* per feedback from Ryan King and Mark Nottingham
## If reviewer is absent from the hReview, then look outside the hReview, in the context of the page, for the reviewer. If there is no "reviewer" outside either, then use the <code><nowiki><address></nowiki></code> for the page as the reviewer.
## MUST (instead of SHOULD) use [[hcard|hCard]] to represent reviewer information
# SHOULD use [[hcalendar|hCalendar]] to represent an item of 'type' 'event'
# Added one decimal digit of precision to ratings' numerical values based on publisher experience.
# Use [http://microformats.org/wiki/hcard#Value_excerpting the "value" construct from hCard] (as it is used in "tel" properties for example) to more explicitly markup the rating value when also providing (marking up) the best/worst of a rating.
# Added [[rel-license]] to indicate the license of the hReview as a whole.
# Permit tags inside ratings to denote rated tags, the same as ratings inside tags per suggestion from Eran Globen.
# Add [[include-pattern]] support to allow multiple reviews for the same item to not repeat the item info.

Informative changes (several, but in particular):
# Note that scalar/rated tags would ideally use a tag space that explain the ratings for that tag. E.g. to explain what Food:18/30 means.
# Updated examples accordingly.

== Discussions ==
* Feedback is encouraged on the [[hreview-feedback]] page.
* See also [http://www.technorati.com/cosmos/referer.html blogs discussing this page].

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

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

hcalendar-brainstorming

2006-02-06T21:20:09Z

PigsOTWing: /* Use in tables */ date fix

= hCalendar Brainstorming =
__TOC__
== Authors ==
* [http://suda.co.uk/ Brian Suda]
* [http://tantek.com/log/ Tantek Çelik]

= BEST-PRACTICES =
Along with the four base properties, you can define addtional properties through the use of the x-prop property. For best-practices for hCal to iCal transformers, it would be helpful if the transforming application added the following x-* properties:

* X-FROM-URL. The value of this property would be the URL of the page where the iCal representation was generated.
<pre><nowiki>
X-FROM-URL:http://example.com/page-containing-hCal-encoding.html
</nowiki></pre>

* X-WR-CALNAME. iCal.app recognizes this property as the "calendar name" for subscribed calendars. Thus transforming applications *should* take the <code><title>...</title></code> from the page being parsed, optionally append " events", and use that value for the X-WR-CALNAME property in the resulting feed. E.g. if the page had <code><title>Example Home Page</title></code> then the .ics output should have as part of the vcalendar object:
<pre><nowiki>
X-WR-CALNAME:Example Home Page
</nowiki></pre>

= Examples =
This is a growing example case written in iCal format and transformed to the corresponding XHTML. These conversions are open to community input.

<pre><nowiki>
BEGIN:VEVENT
CATEGORIES:foo,bar
SUMMARY: Short Title
DESCRIPTION: Full Description
DTSTART;VALUE=DATE:20040101
DTEND:20040101T235959Z
RRULE:FREQ=YEARLY;UNTIL=20080102T000000Z
URL;WORK:http://example.com
ATTENDEE;ROLE=CHAIR:MAILTO:JohnDoe@example.com
GEO:37.386013;-122.082932
END:VEVENT
</nowiki></pre>
<pre><nowiki>


Categories:
<ul class="categories">
<li>foo</li>
<li>bar</li>
</ul>
<a href="http://example.com" class="summary">Short Title</a>
description
37.386013 -122.082932



Date: 20040101 - 20040101T235959Z




<a class="attendee chair" href="mailto:JohnDoe@example.com">John Doe</a>


The event will be held yearly until 20080102T000000Z.


</nowiki></pre>

@@-need to look at nested tag examples
<pre><nowiki>
XHTML
Short Title to a longer article

vCal
SUMMARY:Short Title
DESCRIPTION:Short Title to a longer article
</nowiki></pre>

== Examples from RFC 2445 ==

* <del>Note: this subsection is worthy of being the start of a new page: [[hcalendar-examples]], similar to [[hcard-examples]] -[http://tantek.com/log/ Tantek]</del>
* These examples are now all available on [[hcalendar-examples]] -[[User:RyanKing]]

With the abbr's title attribute being used rather than the node value, the actual data could vary and still represent the same vcalendar.

<pre><nowiki>
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
DTSTART:19970714T170000Z
DTEND:19970715T035959Z
SUMMARY:Bastille Day Party
END:VEVENT
END:VCALENDAR
</nowiki></pre>

<pre><nowiki>


<abbr class="dtstart" title="19970714T170000Z">July 14th</abbr>
<abbr class="dtend" title="19970715T035959Z"></abbr>
Bastille Day Party


</nowiki></pre>

=== UID handling ===

The UID in iCal is represented in HTML as the id attribute in these examples. Any valid id in HTML is a valid UID in iCal, but not the contrapositive, a valid UID is NOT a valid HTML id. HTML ids can only start with a letter, not a number.

<pre><nowiki>
BEGIN:VEVENT
UID:19970901T130000Z-123401@host.com
DTSTAMP:19970901T1300Z
DTSTART:19970903T163000Z
DTEND:19970903T190000Z
SUMMARY:Annual Employee Review
CLASS:PRIVATE
CATEGORIES:BUSINESS,HUMAN RESOURCES
END:VEVENT
</nowiki></pre>

<pre><nowiki>


<abbr title="dtstamp" class="19970901T1300Z"></abbr>
<abbr title="dtstart" class="19970903T163000Z">September 3rd, 4:30pm</abbr>-
<abbr title="dtend" class="19970903T190000Z">7:00pm</abbr>
Annual Employee Review
private
<ul class="categories">
<li>BUSINESS</li>
<li>HUMAN RESOURCES</li>
</ul>


</nowiki></pre>

<pre><nowiki>
BEGIN:VCALENDAR
BEGIN:VEVENT
UID:19970901T130000Z-123402@host.com
DTSTAMP:19970901T1300Z
DTSTART:19970401T163000Z
DTEND:19970402T010000Z
SUMMARY:Laurel is in sensitivity awareness class.
CLASS:PUBLIC
CATEGORIES:BUSINESS,HUMAN RESOURCES
TRANSP:TRANSPARENT
END:VEVENT
END:VCALENDAR
</nowiki></pre>
<pre><nowiki>


<abbr title="dtstamp" class="19970901T1300Z"></abbr>
<abbr title="dtstart" class="19970401T163000Z">April 1st 4:30pm</abbr>-
<abbr title="dtend" class="19970402T010000Z">1:00am</abbr>
Laurel is in sensitivity awareness class.
PUBLIC
<ul class="categories">
<li>BUSINESS</li>
<li>HUMAN RESOURCES</li>
</ul>
Transparent


</nowiki></pre>

=== RRULE handling ===

The way RRULE is encoded should be discussed.

<pre><nowiki>
BEGIN:VEVENT
UID:19970901T130000Z-123403@host.com
DTSTAMP:19970901T1300Z
DTSTART:19971102
SUMMARY:Our Blissful Anniversary
CLASS:CONFIDENTIAL
CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION
RRULE:FREQ=YEARLY
END:VEVENT
</nowiki></pre>
<pre><nowiki>


<abbr title="dtstart" class="19970901T1300Z"></abbr>
<abbr title="dtend" class="19971102">November 2nd</abbr>
Our Blissful Anniversary
CONFIDENTIAL
<ul class="categories">
<li>ANNIVERSARY</li>
<li>PERSONAL</li>
<li>SPECIAL OCCASION</li>
</ul>
YEARLY


</nowiki></pre>

== Examples from real world event sites ==

=== W3C Meetings ===

I just got email announcing the dates of another W3C meeting. I don't think it's marked up with hCalendar. I could mark it up myself, like I did for [http://www.w3.org/2005/12/allgroupoverview.html the TP day/week schedule], but it might not stick. Somehow I got [http://www.w3.org/2000/08/w3c-synd/ our syndicated news markup] (precursor to [[hAtom]]) to stick, i.e. to become part of the norm in the W3C comm team. I wonder if I could pull that off for calendars.

My first thought is authoring tools, but I don't think I can wait that long.
Next thought is instant-feedback checking tools...
X2V is really handy, but can't be used for confidential pages (and many/most calendars I use are not public).
So.. how about some in-browser javascript "yes, you got it right!" or "hmm... that looks like a date; is there an event you didn't mark up?" feedback? I think I saw something like that in hCalendar implementations.

[[User:DanC|DanC]] 09:00, 3 Feb 2006 (PST)

=== Laughing Squid ===

Laughing Squid had the following [http://laughingsquid.com/squidlist/calendar/9584/2005/4/7 multiple occurence event example]:

Thu, Apr 7 : Tu/Wed: 12-4pm Th/Fr/Sat 12-7pm Sun 12-6pm

In addition, later on in the description, it says:

April 7-21, 2005

This is actually quite a non-trivial example, because the event lasts for different durations on different days (4 hours, 7 hours, 6 hours).

Because of the differing durations, the specification requires that *each* instance of this recurring event be explicitly specified.

But first we markup the starting date and time explicitly:
<pre>
<abbr class="dtstart" title="20050407T1200-0700">Thu, Apr 7</abbr> :
</pre>
Then we put in the quite lengthy explicit specification of every other time the event occurs, marked up around the human readable description.
<pre>
<abbr class="rdate" title="20050407T1200-0700/PT7H, 20050408T1200-0700/PT7H,
20050409T1200-0700/PT7H, 20050410T1200-0700/PT6H, 20050412T1200-0700/PT4H,
20050413T1200-0700/PT4H, 200504014T1200-0700/PT7H, 20050415T1200-0700/PT7H,
20050416T1200-0700/PT7H, 20050417T1200-0700/PT6H, 20050419T1200-0700/PT4H,
20050420T1200-0700/PT4H, 20050421T1200-0700/PT7H" >
Tu/Wed: 12-4pm Th/Fr/Sat 12-7pm Sun 12-6pm
</abbr>
</pre>

The RDATE "PERIOD" format is fairly straightforward. You simply list *each* occurrence of the event, separated by commas. Each occurrence consists of the ISO8601 datetime of the start of the event, followed by a slash "/", followed by *either* the duration of the event (e.g. 7 hours = PT7H), *or* a complete ISO8601 datetime of the end of the event. I chose to use the duration of the event for this example for reason of brevity.

Note that "value=period:" is unnecessary in the rdate value since the parser can infer "value=period:" from the presence of a "/" in the title attribute value.

With simpler repeating events, or perhaps events which only repeat a day or two, their hCalendar markup may be more illustrative of how to do this in a general way.

= CSS Styles =
Since the hCal properties are added in as CSS styles, you can style them along with any normal CSS style. You are free to style these properties in any fashion you want (see specific notes), but here are a few examples that you can use.

== Preserving White-space ==
If you are encoding data that requires tabs, returns, or other white-space to be perserved you can use the following CSS property to do so in HTML.
<pre><nowiki>

This white-space
will be
preserved

</nowiki></pre>
white-space can take one of three different parameters; normal, pre, and no-wrap.

== Not recommended ==

The following CSS styling techniques are not recommended:

=== Hiding Data ===
It is possible to encode additional data without it being displayed in the HTML, by using the CSS style property 'display'.
<pre><nowiki>
Hidden Data
</nowiki></pre>
This data will be found by any transforming application and will be properly encoded into an iCal file.

'''You SHOULD NOT do this because it violates the visibility priniciple.'''

= Tutorials =
How to include hCal encodings into your favourite Blogging Software.

= Open Questions =
== General Questions ==
Q: Should Transforming applications purely extract the information and ignore validity? or should there be some checking, or should this be left to the importing application? (i.e. DTSTART;VALUE=DATE: This-Is-Not-a-proper-date)

A: The simpler the better. Other than checking for perhaps X(HT)ML validity, it should be a simple translator, because presumably the receiving iCalendar application has to have malformed .ics handling already. Let's avoid duplicating that. -- [http://tantek.com/ Tantek Çelik]

Q: What about multiple of the instances same vCal entity? (two instances of DTSTART) Is this left up to the importing application, or should the XSLT transformation fail?

A: Same as previous. Leave it up to the importing application to interpret it per the iCalendar spec, e.g. what does RFC2445 say about two instances of DTSTART? -- [http://tantek.com/ Tantek Çelik]

From RFC2445:
4.1.2 Multiple Values
Some properties defined in the iCalendar object can have multiple values. The general rule for encoding multi-valued items is to simply create a new content line for each value, including the property name. However, it should be noted that some properties support encoding multiple values in a single property by separating the values with a COMMA character (US-ASCII decimal 44). Individual property definitions should be consulted for determining whether a specific property allows multiple values and in which of these two forms.

Other than that, it does not mention what to do ABOUT invalid data, or which of the multiple entries takes precedence. The only mention of duplicate instances is in the RRULE and EXDATE rules where events exclusions/inclusions overlap. Then duplicate instances are ignore. If it is explicitly written for those items, but NOT for things like DTSTART, then it is difficult to assume duplicate instances are ignored for them as well.

Each of the Components (VEVENT, ...) define which properties can exisit and in what quantity. So multiple DTSTART properties are NOT allowed.
-- [http://suda.co.uk Brian Suda]

Q: Should vCal entitles be represented in XHTML in classes ONLY on block-level element? or should some like VEVENT be block-level and others be of any? does this impact the semantics at all?

A: I don't think the (X)HTML notion of "block-level" should have any bearing whatsoever on vCal entities. You should be able to say or <div class="vevent"> and either should work.

Q: Should the transforming application add any additional information to the iCalendar representation other than what was encoded in the HTML? (i.e. UID, the unique identifier might not be present in the HTML code, but could be generated by the transforming application and added to the iCal file. Should this be allowed? or should the transforming app ONLY be allowed to add X-PROPERTY properties?) IF it was not explicitly encoded in the HTML should it be left out? What about default values?

Q: If we are looking at the most semantic way to encoding iCalendar data in HTML then several other attributes should be considered besides just 'class'. There are two other candidated, ID and REL. The ID tag MUST be unique within the XHTML file (this could be used for the UID property). The REL attribute can ONLY be applied to 'a' and 'link' tags, but might be helpful. Are namespac<ETH>H �n option? xml:lang, xml:base, are there any others that might be more semantically correct to encode this data?

Q: To help distinguish xparam values from other actual CSS styles, should we assume/mandate that all values in a class attribute within an encoded iCal component class attribute (<x class="vevent|vtodo|...">) be considered an xparam?

A: If you are using other CSS styles (e.g. "center", "bluebox", "greenline", etc.) nested within an iCal component, those should be avoided and the styles applied to the list of iCal properties instead/also?

<pre><nowiki>
.center, .vevent { text-align: center; }
</nowiki></pre>

Q: What about cases where the words "yesterday", "last year", or "last week" was used? How should we represent this? Is this overkill or not appropriate for hcard ? - [[User:B.K._DeLong]]

A: I took a stab at "yesterday" and just added a dtstart of the previous day. Not sure how to represent a single year or whole week - [[User:B.K._DeLong]]

<pre><nowiki>
<abbr class="dtstart" title="20050114">Yesterday's</abbr>
</nowiki></pre>

== Recurring Events ==

Recurring events are tricky. First, there's the question of whether to follow ''For types with multiple components, use nested elements with class names equivalent to the names of the components'' a la
<pre>
<nowiki><div class="rrule">every 1
WEEKLY on TU
until 2004-11-01</div></nowiki>
</pre>
... or ...
<pre>
<nowiki><abbr class="rrule" title="FREQ=WEEKLY;COUNT=17;INTERVAL=2;BYDAY=TH"> every other
Thursday for 34 weeks</abbr></nowiki>
</pre>
... as in [http://microformats.org/discuss/mail/microformats-discuss/2005-August/000516.html Tantek's 1 Aug msg].

[http://www.w3.org/People/Connolly/ DanC] has been experimenting with representing his PDA calendar in hCalendar:

* in [http://dev.w3.org/cvsweb/2001/palmagent/ palmagent], there's dangerSync.py which uses the XMLRPC interface and spits out RDF data. Then asHCal.xsl converts that to hCalendar
* then in [http://www.w3.org/2002/12/cal/ the RDF Calendar workspace], there's [http://www.w3.org/2002/12/cal/glean-hcal.xsl glean-hcal.xsl] that turns hCalendar into RDF Calendar, and finally,
* in [http://www.w3.org/2000/10/swap/ SWAP] there's [http://www.w3.org/2000/10/swap/pim/toIcal.py toIcal.py] that turns RDF Calendar to .ics format.

So I can go from my sidekick to .ics with one Makefile.

[http://dev.w3.org/cvsweb/2001/palmagent/event-test.html events-test.html] is a test file that has all the constructs from my PDA data, in hCalendar. In particular, it uses the nested element representation of recurring events. glean-hcal.xsl would be much less fun to write if it had to parse <nowiki>title="FREQ=WEEKLY;COUNT=17;INTERVAL=2;BYDAY=TH"</nowiki>.

Then there's the question of "every tuesday afternoon at 2pm Chicago time". This isn't expressible using [[datetime-design-pattern]]. There are some good reasons for that, but it leaves a rather large and uncomfortable gap in hCalendar.

== Encoding Questions ==
The way dates are encoded is not always the most user friendly. If i want to encode january 1st, 2005, that is <code>20050101</code>, which is displayed as 20050101. If we are marking-up comma seperated values, like FN, with each sub-element inside their own tag, then the date should be allowed the same.

(However, FN is in the RFC2426 spec and vCard schema, these individual date terms are not, therefore the reasoning in the last sentence is incorrect. -[http://tantek.com/log/ Tantek])

<pre><nowiki>
20050101
20050101
</nowiki></pre>
With this encoding, then YYYYMMDD schema can be rearranged for different cultures, DD-MM-YYYY for UK, MM-DD-YYYY for US, etc.
<pre><nowiki>
02-01-2005
02-01-2005
01-02-2005
01-02-2005
</nowiki></pre>
Both of the above encodings are equal, the '-' seperator is ignored by the transforming application. -- [http://suda.co.uk Brian Suda]

Agreed that the way dates are encoded is not always the most user friendly, but there is an easier solution to this, once you think of what is actually going on in the difference between ISO8601 dates, and dates the way humans use them. Humans typically use an abbrevation or shorthand for a date, like "tomorrow", or "Tuesday", or "the 4th", or perhaps "July 4th". Thus it makes sense to permit this in hCalendar, using the <code><abbr></code> tag which provides the ability to markup the human-familiar short form of some data or language, while preserving the long form in the 'title' attribute.

E.g. for the above example of a start date of January 1st, 2005, you could use this markup:

<pre><nowiki>
<abbr class="dtstart" title="20050101">January 1st, 2005</abbr>
</nowiki></pre>

Which would display as <code>January 1st, 2005</code> but would provide the respective ISO8601 date in the title attribute. - [http://tantek.com/log Tantek]

= TODO =
A HTML head profile needs creation and a home.

== Applications ==
A simple implementation of transforming/extracting vCal data from an XHTML file is available for testing. A bookmarklet is also available. The code will be updated as the spec is finalised.
http://suda.co.uk/projects/X2V/

== Parsing ==

Need to write up an [[hcalendar-parsing]] document, similar to [[hcard-parsing]].

=== Tabular Data ===

Many calendars are posted in tabular form, where the headings on the columns and rows have property values that apply to the cells which themselves are events.

(TODO: document "How To" for marking up tabular event listings)

To enable mark these up with [[hcalendar|hCalendar]], we must parse additional semantic attributes from HTML4.

When parsing, in addition to the special case rules documented in [[hcard-parsing]]:

* If the element is a table data cell <code><td></code>, then:
*# parse its "headers" attribute as a space separated set of local IDs
*# find the <code><td></code> and <code><th></code> elements referenced by those IDs (call them header cells) and consider them part of the element being parsed as follows:
*## Treat the header cells as children of the element, ordered by the order of ids in its "headers" attribute, immediately following the last child node (text or element) or the element. (The basic idea is that the content from those header cells is used to construct the VEVENT, but secondary to (AFTER) the content in the data cell itself, so that the data cell can customize/override part of the data in the header, e.g. if the header cell included both start time and location, and the event was being held at a different location).
*## Parse the "axis" attribute of a header cell as a comma-separated list of categories. These categories must be used in addition to (and before) any class names on that header cell for determining whether it is a property of the VEVENT.

== Relationships with other microformats ==

In a [http://www.technologyreview.com/articles/04/10/frauenfelder1004.asp Technology Review interview], TBL said "It would have the relationships between the event and the various people chairing it.".

We should have examples of how hCalendar events can indicate such relationships, both in the format and in the presentation.
E.g.:
* Would it just link to URLs for the various people? (e.g. to their homepages/blogs etc.)
* Would it include hCards for the various people?
* Would it link to hCards for various people?
* Perhaps allow all the above?

== Mime-Type ==
According to RFC2445, the proposed media type value is 'text/calendar'.

A standard vCalendar file has an extension of .vcs and MIME type of text/x-vCalendar. If you use iCalendar, the MIME type is "text/Calendar" and the extension is .ics.

Text/X-vCalendar Content Type
The vCalendar object can also be passed as a non-standard MIME media type. This would be useful in order to clearly identify the vCalendar object in an electronic mail message body part. A non-standard, vCalendar object should be identified as the MIME type/subtype "text/x-vCalendar".

@@ - i have to do some more investigation, but (i think) vCalendar is a subset of iCalendar, so many of the same encodings will work for both, but this document is dealing with iCalendar RFC2445 representation!

== Button ==

We need to come up with a nice <code>[ hCal | friendly ]</code> button to indicate that event info on a page/site is using hCalendar. - [http://tantek.com/log/ Tantek].

Possibilities:
* <code>[ hCal | friendly ]</code>
* <code>[ hCal | aware ]</code>
* <code>[ hCal | inside ]</code>
* <code>[ Valid | hCalendar ]</code> - though that would require writing an hCalendar validator which people could link to.
* <code>[ <icon> | hCalendar ]</code> where <icon> could be some generic calendar looking thing, or it could be a PHP generated image with the actual date in the icon, kind of like how the Apple iCal icon updates in the dock automatically.

And then we have to pick colors and all that stuff - [http://tantek.com/log/ Tantek].

Other ideas:
* <code>[ hCal | enabled ]</code>
* <code>[ hCal | available ]</code> - kind of an off-hand reference to being available for meetings, etc.

- [http://meyerweb.com/ Eric]

== Including More of iCalendar ==

=== Free/Busy information ===

See [http://www.ifreebusy.com/cyclical/blog/ Neil Jensen]'s [http://www.ifreebusy.com/cyclical/blog/calendar/3 analysis of how to represent the iCalendar VFREEBUSY object in hCalendar].

In order to show free/busy information, we could either use the existing vevent class (with empty location, summary, etc. properties) or create a new vfreebusy class. We should create a new vfreebusy class because it is consistent with the XHTML design principles, particularly point #4, "Use class names based on names from the original schema...".

In the iCalendar standard, the vfreebusy calendar component frequently has more than one freebusy property, and also may have a number of other properties such as organizer. For example:

<pre><nowiki>
BEGIN:VFREEBUSY
ORGANIZER:jsmith@host.com
DTSTART:19980313T141711Z
DTEND:19980410T141711Z
FREEBUSY:19980314T233000Z/19980315T003000Z
FREEBUSY:19980316T153000Z/19980316T163000Z
FREEBUSY:19980318T030000Z/19980318T040000Z
URL:http://www.host.com/calendar/busytime/jsmith.ifb
END:VFREEBUSY
</nowiki></pre>

So, our hCalendar representation should include separate elements for the vfreebusy calendar component (defined once) and the freebusy property (possibly defined many times):

<pre><nowiki>


<abbr class="dtstart" title="20050721T1000-0800">
July 21, 2005 - 10:00
</abbr> -
<abbr class="dtend" title="20050721T1100-0800">
11:00
</abbr>
 

<abbr class="dtstart" title="20050722T1000-0800">
July 22, 2005 - 10:00
</abbr> -
<abbr class="dtend" title="20050722T1100-0800">
11:00
</abbr>
 

</nowiki></pre>

According to RFC2445, "When publishing a "VFREEBUSY" calendar component, the property is used to specify the calendar that the published busy time came from." The property type is CAL-ADDRESS, and can include "non-standard, language, common name and directory entry reference" property parameters. CAL-ADDRESS is "...a URI as defined by [RFC 1738] or any other IANA registered form...".

From what I've seen, Microsoft Outlook typically populates this property with the email address of the calendar owner, which initially made me think of using hCard to specify the organizer. However, given that the property refers to the calendar and not necessarily the person who owns or has published it, I think we should use a new organizer element, as shown below:

<pre><nowiki>
BEGIN:VFREEBUSY
ORGANIZER:jsmith@host.com
FREEBUSY:20050314T133000Z/20050314T163000Z
END:VFREEBUSY
</nowiki></pre>

becomes

<pre><nowiki>

organizer: jsmith@host.com

<abbr class="dtstart" title="20050314T133000Z">
March 14, 2005 - 13:30
</abbr> -
<abbr class="dtend" title="20050314T163000Z">
16:30
</abbr>
 

</nowiki></pre>

Hmmm, this looks a little funny when the organizer is so obviously an email address, but at least it is semantically correct. The other problem that I can now see occurring is when the organizer property has parameters, for example (from the iCalendar spec):

<pre><nowiki>
ORGANIZER;CN=JohnSmith;DIR="ldap://host.com:6666/o=3DDC%20Associ
ates,c=3DUS??(cn=3DJohn%20Smith)":MAILTO:jsmith@host1.com
</nowiki></pre>

Perhaps it's best to use the same approach described in "Human vs. ISO8601 dates problem solved"; use the abbr element like so:

<pre><nowiki>


organizer: <abbr class="organizer" title="CN=JohnSmith;DIR=ldap://host.com:6666/o=3DDC%20Associ
ates,c=3DUS??(cn=3DJohn%20Smith):MAILTO:jsmith@host1.com">jsmith@host1.com</abbr>
<abbr class="dtstart" title="20050314T133000Z">
March 14, 2005 - 13:30
</abbr> -
<abbr class="dtend" title="20050314T163000Z">
16:30
</abbr>


</nowiki></pre>

=== To-Do information ===

The [http://www.policyawareweb.org/2005/ftf2/paw-mtg Policy Aware Web (PAW) Project Meeting - 23 Aug 2005] uses class="vtodo" to capture action items. Clearly recording action items from a meeting and publishing them as minutes is a good practical example use of the VTODO object on the web.

What's the scenario for usage though?

What kind of indexer/aggregator application would find these VTODO items and what would it do with them?

Perhaps with some way of figuring out who the to-do item is assigned to ("ATTENDEE"), who assigned it ("DELEGATED-FROM"), and a whitelisting of who, perhaps the "ORGANIZER" property, (and their domains/URLs) that a user would accept assignments from, a user could aggregate to-do items assigned from other folks. Then question remains how to update the status ("STATUS") (RFC 2445 4.8.1.11 Status) on that to-do item when it is (a) completed ("COMPLETED"), (b) abandoned/cut/rejected ("CANCELLED"), (c) some progress is made ("IN-PROCESS") etc. There certainly seems to be sufficient expressiveness in VTODO and its properties to do a decentralized to-do list / task distribution system. Could be very interesting for helping open source projects and other distributed teams do project management using the Web.

= References =
== Normative References ==
* [http://www.ietf.org/rfc/rfc2445.txt RFC 2445]
* [http://gmpg.org/xmdp/ XMDP]

== Informative References ==
* [http://wiki.oreillynet.com/foocamp04/index.cgi?HTMLForCalendars HTMLForCalendars (FOO camp)] - presented just a few days before this, hopefully these efforts can be combine

* [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]
* [http://www.ietf.org/rfc/rfc2446.txt iTIP RFC2446]
* [http://www.ietf.org/rfc/rfc2447.txt iMIP RFC2447]
* [http://www.ietf.org/rfc/rfc3283.txt Guide to Internet Calendaring RFC3283]

== Other Implementations/Ideas ==
* [http://www.nehmer.net/~bergie/openpsa-calendar-horizontal.jpg OpenPSA calendar screenshot]
* [http://www.w3.org/2002/12/cal/ RDF Calendar Workspace] - some older work done with RDF, not really applicable to the simple XHTML case, but perhaps worthy of analysis for when and why they may have diverged from established iCalendar schemas.
* [http://planb.nicecupoftea.org/archives/000072.html 2003 RDF icalendar work, xCal references]

== Blogs About Calendaring ==
* http://staff.washington.edu/oren/weblog2/

=Use in tables=
I currently have [http://www.westmidlandbirdclub.com/birmingham/field.htm events in table layout], using the format:
<pre><nowiki>
<tr class="X">
<th scope="row">Sunday 12 February 2006</th>
<td><a href="http://www.rspb.org.uk/reserves/guide/c/conwy/index.asp">RSPB Conwy</a>*/ Llanfairfechan.</td>
<td>A sea watch with potential for divers and sea ducks and a visit to a prime seaside reserve.</td>
</tr>
</nowiki></pre>

How would I include the code:
<pre><nowiki>
<div class="vevent">
<a class="url" href="http://www.westmidlandbirdclub.com/birmingham/field.htm">
<abbr class="dtstart" title="20060212">February 12 2006</abbr>
<abbr class="dtend" title="20060213"> </abbr>
Birmingham Branch Field Trip - at
RSPB Conwy/ Llanfairfechan.
</a>
<div class="description">A sea watch with potential for divers and sea ducks and a visit to a prime seaside reserve.</div>
</div>
</nowiki></pre>
in that? It seems to me that to loose the semantic table mark (column and row headers, for example) up would be a bad thing; not least for people whose lints don't understand hCal. Is the use of a non-breaking space in the dtend OK?[[User:PigsOTWing|PigsOTWing]] 12:12, 6 Feb 2006 (PST)

hcalendar-brainstorming

2006-02-06T21:14:10Z

PigsOTWing: /* References */ fix header depth

= hCalendar Brainstorming =
__TOC__
== Authors ==
* [http://suda.co.uk/ Brian Suda]
* [http://tantek.com/log/ Tantek Çelik]

= BEST-PRACTICES =
Along with the four base properties, you can define addtional properties through the use of the x-prop property. For best-practices for hCal to iCal transformers, it would be helpful if the transforming application added the following x-* properties:

* X-FROM-URL. The value of this property would be the URL of the page where the iCal representation was generated.
<pre><nowiki>
X-FROM-URL:http://example.com/page-containing-hCal-encoding.html
</nowiki></pre>

* X-WR-CALNAME. iCal.app recognizes this property as the "calendar name" for subscribed calendars. Thus transforming applications *should* take the <code><title>...</title></code> from the page being parsed, optionally append " events", and use that value for the X-WR-CALNAME property in the resulting feed. E.g. if the page had <code><title>Example Home Page</title></code> then the .ics output should have as part of the vcalendar object:
<pre><nowiki>
X-WR-CALNAME:Example Home Page
</nowiki></pre>

= Examples =
This is a growing example case written in iCal format and transformed to the corresponding XHTML. These conversions are open to community input.

<pre><nowiki>
BEGIN:VEVENT
CATEGORIES:foo,bar
SUMMARY: Short Title
DESCRIPTION: Full Description
DTSTART;VALUE=DATE:20040101
DTEND:20040101T235959Z
RRULE:FREQ=YEARLY;UNTIL=20080102T000000Z
URL;WORK:http://example.com
ATTENDEE;ROLE=CHAIR:MAILTO:JohnDoe@example.com
GEO:37.386013;-122.082932
END:VEVENT
</nowiki></pre>
<pre><nowiki>


Categories:
<ul class="categories">
<li>foo</li>
<li>bar</li>
</ul>
<a href="http://example.com" class="summary">Short Title</a>
description
37.386013 -122.082932



Date: 20040101 - 20040101T235959Z




<a class="attendee chair" href="mailto:JohnDoe@example.com">John Doe</a>


The event will be held yearly until 20080102T000000Z.


</nowiki></pre>

@@-need to look at nested tag examples
<pre><nowiki>
XHTML
Short Title to a longer article

vCal
SUMMARY:Short Title
DESCRIPTION:Short Title to a longer article
</nowiki></pre>

== Examples from RFC 2445 ==

* <del>Note: this subsection is worthy of being the start of a new page: [[hcalendar-examples]], similar to [[hcard-examples]] -[http://tantek.com/log/ Tantek]</del>
* These examples are now all available on [[hcalendar-examples]] -[[User:RyanKing]]

With the abbr's title attribute being used rather than the node value, the actual data could vary and still represent the same vcalendar.

<pre><nowiki>
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
DTSTART:19970714T170000Z
DTEND:19970715T035959Z
SUMMARY:Bastille Day Party
END:VEVENT
END:VCALENDAR
</nowiki></pre>

<pre><nowiki>


<abbr class="dtstart" title="19970714T170000Z">July 14th</abbr>
<abbr class="dtend" title="19970715T035959Z"></abbr>
Bastille Day Party


</nowiki></pre>

=== UID handling ===

The UID in iCal is represented in HTML as the id attribute in these examples. Any valid id in HTML is a valid UID in iCal, but not the contrapositive, a valid UID is NOT a valid HTML id. HTML ids can only start with a letter, not a number.

<pre><nowiki>
BEGIN:VEVENT
UID:19970901T130000Z-123401@host.com
DTSTAMP:19970901T1300Z
DTSTART:19970903T163000Z
DTEND:19970903T190000Z
SUMMARY:Annual Employee Review
CLASS:PRIVATE
CATEGORIES:BUSINESS,HUMAN RESOURCES
END:VEVENT
</nowiki></pre>

<pre><nowiki>


<abbr title="dtstamp" class="19970901T1300Z"></abbr>
<abbr title="dtstart" class="19970903T163000Z">September 3rd, 4:30pm</abbr>-
<abbr title="dtend" class="19970903T190000Z">7:00pm</abbr>
Annual Employee Review
private
<ul class="categories">
<li>BUSINESS</li>
<li>HUMAN RESOURCES</li>
</ul>


</nowiki></pre>

<pre><nowiki>
BEGIN:VCALENDAR
BEGIN:VEVENT
UID:19970901T130000Z-123402@host.com
DTSTAMP:19970901T1300Z
DTSTART:19970401T163000Z
DTEND:19970402T010000Z
SUMMARY:Laurel is in sensitivity awareness class.
CLASS:PUBLIC
CATEGORIES:BUSINESS,HUMAN RESOURCES
TRANSP:TRANSPARENT
END:VEVENT
END:VCALENDAR
</nowiki></pre>
<pre><nowiki>


<abbr title="dtstamp" class="19970901T1300Z"></abbr>
<abbr title="dtstart" class="19970401T163000Z">April 1st 4:30pm</abbr>-
<abbr title="dtend" class="19970402T010000Z">1:00am</abbr>
Laurel is in sensitivity awareness class.
PUBLIC
<ul class="categories">
<li>BUSINESS</li>
<li>HUMAN RESOURCES</li>
</ul>
Transparent


</nowiki></pre>

=== RRULE handling ===

The way RRULE is encoded should be discussed.

<pre><nowiki>
BEGIN:VEVENT
UID:19970901T130000Z-123403@host.com
DTSTAMP:19970901T1300Z
DTSTART:19971102
SUMMARY:Our Blissful Anniversary
CLASS:CONFIDENTIAL
CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION
RRULE:FREQ=YEARLY
END:VEVENT
</nowiki></pre>
<pre><nowiki>


<abbr title="dtstart" class="19970901T1300Z"></abbr>
<abbr title="dtend" class="19971102">November 2nd</abbr>
Our Blissful Anniversary
CONFIDENTIAL
<ul class="categories">
<li>ANNIVERSARY</li>
<li>PERSONAL</li>
<li>SPECIAL OCCASION</li>
</ul>
YEARLY


</nowiki></pre>

== Examples from real world event sites ==

=== W3C Meetings ===

I just got email announcing the dates of another W3C meeting. I don't think it's marked up with hCalendar. I could mark it up myself, like I did for [http://www.w3.org/2005/12/allgroupoverview.html the TP day/week schedule], but it might not stick. Somehow I got [http://www.w3.org/2000/08/w3c-synd/ our syndicated news markup] (precursor to [[hAtom]]) to stick, i.e. to become part of the norm in the W3C comm team. I wonder if I could pull that off for calendars.

My first thought is authoring tools, but I don't think I can wait that long.
Next thought is instant-feedback checking tools...
X2V is really handy, but can't be used for confidential pages (and many/most calendars I use are not public).
So.. how about some in-browser javascript "yes, you got it right!" or "hmm... that looks like a date; is there an event you didn't mark up?" feedback? I think I saw something like that in hCalendar implementations.

[[User:DanC|DanC]] 09:00, 3 Feb 2006 (PST)

=== Laughing Squid ===

Laughing Squid had the following [http://laughingsquid.com/squidlist/calendar/9584/2005/4/7 multiple occurence event example]:

Thu, Apr 7 : Tu/Wed: 12-4pm Th/Fr/Sat 12-7pm Sun 12-6pm

In addition, later on in the description, it says:

April 7-21, 2005

This is actually quite a non-trivial example, because the event lasts for different durations on different days (4 hours, 7 hours, 6 hours).

Because of the differing durations, the specification requires that *each* instance of this recurring event be explicitly specified.

But first we markup the starting date and time explicitly:
<pre>
<abbr class="dtstart" title="20050407T1200-0700">Thu, Apr 7</abbr> :
</pre>
Then we put in the quite lengthy explicit specification of every other time the event occurs, marked up around the human readable description.
<pre>
<abbr class="rdate" title="20050407T1200-0700/PT7H, 20050408T1200-0700/PT7H,
20050409T1200-0700/PT7H, 20050410T1200-0700/PT6H, 20050412T1200-0700/PT4H,
20050413T1200-0700/PT4H, 200504014T1200-0700/PT7H, 20050415T1200-0700/PT7H,
20050416T1200-0700/PT7H, 20050417T1200-0700/PT6H, 20050419T1200-0700/PT4H,
20050420T1200-0700/PT4H, 20050421T1200-0700/PT7H" >
Tu/Wed: 12-4pm Th/Fr/Sat 12-7pm Sun 12-6pm
</abbr>
</pre>

The RDATE "PERIOD" format is fairly straightforward. You simply list *each* occurrence of the event, separated by commas. Each occurrence consists of the ISO8601 datetime of the start of the event, followed by a slash "/", followed by *either* the duration of the event (e.g. 7 hours = PT7H), *or* a complete ISO8601 datetime of the end of the event. I chose to use the duration of the event for this example for reason of brevity.

Note that "value=period:" is unnecessary in the rdate value since the parser can infer "value=period:" from the presence of a "/" in the title attribute value.

With simpler repeating events, or perhaps events which only repeat a day or two, their hCalendar markup may be more illustrative of how to do this in a general way.

= CSS Styles =
Since the hCal properties are added in as CSS styles, you can style them along with any normal CSS style. You are free to style these properties in any fashion you want (see specific notes), but here are a few examples that you can use.

== Preserving White-space ==
If you are encoding data that requires tabs, returns, or other white-space to be perserved you can use the following CSS property to do so in HTML.
<pre><nowiki>

This white-space
will be
preserved

</nowiki></pre>
white-space can take one of three different parameters; normal, pre, and no-wrap.

== Not recommended ==

The following CSS styling techniques are not recommended:

=== Hiding Data ===
It is possible to encode additional data without it being displayed in the HTML, by using the CSS style property 'display'.
<pre><nowiki>
Hidden Data
</nowiki></pre>
This data will be found by any transforming application and will be properly encoded into an iCal file.

'''You SHOULD NOT do this because it violates the visibility priniciple.'''

= Tutorials =
How to include hCal encodings into your favourite Blogging Software.

= Open Questions =
== General Questions ==
Q: Should Transforming applications purely extract the information and ignore validity? or should there be some checking, or should this be left to the importing application? (i.e. DTSTART;VALUE=DATE: This-Is-Not-a-proper-date)

A: The simpler the better. Other than checking for perhaps X(HT)ML validity, it should be a simple translator, because presumably the receiving iCalendar application has to have malformed .ics handling already. Let's avoid duplicating that. -- [http://tantek.com/ Tantek Çelik]

Q: What about multiple of the instances same vCal entity? (two instances of DTSTART) Is this left up to the importing application, or should the XSLT transformation fail?

A: Same as previous. Leave it up to the importing application to interpret it per the iCalendar spec, e.g. what does RFC2445 say about two instances of DTSTART? -- [http://tantek.com/ Tantek Çelik]

From RFC2445:
4.1.2 Multiple Values
Some properties defined in the iCalendar object can have multiple values. The general rule for encoding multi-valued items is to simply create a new content line for each value, including the property name. However, it should be noted that some properties support encoding multiple values in a single property by separating the values with a COMMA character (US-ASCII decimal 44). Individual property definitions should be consulted for determining whether a specific property allows multiple values and in which of these two forms.

Other than that, it does not mention what to do ABOUT invalid data, or which of the multiple entries takes precedence. The only mention of duplicate instances is in the RRULE and EXDATE rules where events exclusions/inclusions overlap. Then duplicate instances are ignore. If it is explicitly written for those items, but NOT for things like DTSTART, then it is difficult to assume duplicate instances are ignored for them as well.

Each of the Components (VEVENT, ...) define which properties can exisit and in what quantity. So multiple DTSTART properties are NOT allowed.
-- [http://suda.co.uk Brian Suda]

Q: Should vCal entitles be represented in XHTML in classes ONLY on block-level element? or should some like VEVENT be block-level and others be of any? does this impact the semantics at all?

A: I don't think the (X)HTML notion of "block-level" should have any bearing whatsoever on vCal entities. You should be able to say or <div class="vevent"> and either should work.

Q: Should the transforming application add any additional information to the iCalendar representation other than what was encoded in the HTML? (i.e. UID, the unique identifier might not be present in the HTML code, but could be generated by the transforming application and added to the iCal file. Should this be allowed? or should the transforming app ONLY be allowed to add X-PROPERTY properties?) IF it was not explicitly encoded in the HTML should it be left out? What about default values?

Q: If we are looking at the most semantic way to encoding iCalendar data in HTML then several other attributes should be considered besides just 'class'. There are two other candidated, ID and REL. The ID tag MUST be unique within the XHTML file (this could be used for the UID property). The REL attribute can ONLY be applied to 'a' and 'link' tags, but might be helpful. Are namespac<ETH>H �n option? xml:lang, xml:base, are there any others that might be more semantically correct to encode this data?

Q: To help distinguish xparam values from other actual CSS styles, should we assume/mandate that all values in a class attribute within an encoded iCal component class attribute (<x class="vevent|vtodo|...">) be considered an xparam?

A: If you are using other CSS styles (e.g. "center", "bluebox", "greenline", etc.) nested within an iCal component, those should be avoided and the styles applied to the list of iCal properties instead/also?

<pre><nowiki>
.center, .vevent { text-align: center; }
</nowiki></pre>

Q: What about cases where the words "yesterday", "last year", or "last week" was used? How should we represent this? Is this overkill or not appropriate for hcard ? - [[User:B.K._DeLong]]

A: I took a stab at "yesterday" and just added a dtstart of the previous day. Not sure how to represent a single year or whole week - [[User:B.K._DeLong]]

<pre><nowiki>
<abbr class="dtstart" title="20050114">Yesterday's</abbr>
</nowiki></pre>

== Recurring Events ==

Recurring events are tricky. First, there's the question of whether to follow ''For types with multiple components, use nested elements with class names equivalent to the names of the components'' a la
<pre>
<nowiki><div class="rrule">every 1
WEEKLY on TU
until 2004-11-01</div></nowiki>
</pre>
... or ...
<pre>
<nowiki><abbr class="rrule" title="FREQ=WEEKLY;COUNT=17;INTERVAL=2;BYDAY=TH"> every other
Thursday for 34 weeks</abbr></nowiki>
</pre>
... as in [http://microformats.org/discuss/mail/microformats-discuss/2005-August/000516.html Tantek's 1 Aug msg].

[http://www.w3.org/People/Connolly/ DanC] has been experimenting with representing his PDA calendar in hCalendar:

* in [http://dev.w3.org/cvsweb/2001/palmagent/ palmagent], there's dangerSync.py which uses the XMLRPC interface and spits out RDF data. Then asHCal.xsl converts that to hCalendar
* then in [http://www.w3.org/2002/12/cal/ the RDF Calendar workspace], there's [http://www.w3.org/2002/12/cal/glean-hcal.xsl glean-hcal.xsl] that turns hCalendar into RDF Calendar, and finally,
* in [http://www.w3.org/2000/10/swap/ SWAP] there's [http://www.w3.org/2000/10/swap/pim/toIcal.py toIcal.py] that turns RDF Calendar to .ics format.

So I can go from my sidekick to .ics with one Makefile.

[http://dev.w3.org/cvsweb/2001/palmagent/event-test.html events-test.html] is a test file that has all the constructs from my PDA data, in hCalendar. In particular, it uses the nested element representation of recurring events. glean-hcal.xsl would be much less fun to write if it had to parse <nowiki>title="FREQ=WEEKLY;COUNT=17;INTERVAL=2;BYDAY=TH"</nowiki>.

Then there's the question of "every tuesday afternoon at 2pm Chicago time". This isn't expressible using [[datetime-design-pattern]]. There are some good reasons for that, but it leaves a rather large and uncomfortable gap in hCalendar.

== Encoding Questions ==
The way dates are encoded is not always the most user friendly. If i want to encode january 1st, 2005, that is <code>20050101</code>, which is displayed as 20050101. If we are marking-up comma seperated values, like FN, with each sub-element inside their own tag, then the date should be allowed the same.

(However, FN is in the RFC2426 spec and vCard schema, these individual date terms are not, therefore the reasoning in the last sentence is incorrect. -[http://tantek.com/log/ Tantek])

<pre><nowiki>
20050101
20050101
</nowiki></pre>
With this encoding, then YYYYMMDD schema can be rearranged for different cultures, DD-MM-YYYY for UK, MM-DD-YYYY for US, etc.
<pre><nowiki>
02-01-2005
02-01-2005
01-02-2005
01-02-2005
</nowiki></pre>
Both of the above encodings are equal, the '-' seperator is ignored by the transforming application. -- [http://suda.co.uk Brian Suda]

Agreed that the way dates are encoded is not always the most user friendly, but there is an easier solution to this, once you think of what is actually going on in the difference between ISO8601 dates, and dates the way humans use them. Humans typically use an abbrevation or shorthand for a date, like "tomorrow", or "Tuesday", or "the 4th", or perhaps "July 4th". Thus it makes sense to permit this in hCalendar, using the <code><abbr></code> tag which provides the ability to markup the human-familiar short form of some data or language, while preserving the long form in the 'title' attribute.

E.g. for the above example of a start date of January 1st, 2005, you could use this markup:

<pre><nowiki>
<abbr class="dtstart" title="20050101">January 1st, 2005</abbr>
</nowiki></pre>

Which would display as <code>January 1st, 2005</code> but would provide the respective ISO8601 date in the title attribute. - [http://tantek.com/log Tantek]

= TODO =
A HTML head profile needs creation and a home.

== Applications ==
A simple implementation of transforming/extracting vCal data from an XHTML file is available for testing. A bookmarklet is also available. The code will be updated as the spec is finalised.
http://suda.co.uk/projects/X2V/

== Parsing ==

Need to write up an [[hcalendar-parsing]] document, similar to [[hcard-parsing]].

=== Tabular Data ===

Many calendars are posted in tabular form, where the headings on the columns and rows have property values that apply to the cells which themselves are events.

(TODO: document "How To" for marking up tabular event listings)

To enable mark these up with [[hcalendar|hCalendar]], we must parse additional semantic attributes from HTML4.

When parsing, in addition to the special case rules documented in [[hcard-parsing]]:

* If the element is a table data cell <code><td></code>, then:
*# parse its "headers" attribute as a space separated set of local IDs
*# find the <code><td></code> and <code><th></code> elements referenced by those IDs (call them header cells) and consider them part of the element being parsed as follows:
*## Treat the header cells as children of the element, ordered by the order of ids in its "headers" attribute, immediately following the last child node (text or element) or the element. (The basic idea is that the content from those header cells is used to construct the VEVENT, but secondary to (AFTER) the content in the data cell itself, so that the data cell can customize/override part of the data in the header, e.g. if the header cell included both start time and location, and the event was being held at a different location).
*## Parse the "axis" attribute of a header cell as a comma-separated list of categories. These categories must be used in addition to (and before) any class names on that header cell for determining whether it is a property of the VEVENT.

== Relationships with other microformats ==

In a [http://www.technologyreview.com/articles/04/10/frauenfelder1004.asp Technology Review interview], TBL said "It would have the relationships between the event and the various people chairing it.".

We should have examples of how hCalendar events can indicate such relationships, both in the format and in the presentation.
E.g.:
* Would it just link to URLs for the various people? (e.g. to their homepages/blogs etc.)
* Would it include hCards for the various people?
* Would it link to hCards for various people?
* Perhaps allow all the above?

== Mime-Type ==
According to RFC2445, the proposed media type value is 'text/calendar'.

A standard vCalendar file has an extension of .vcs and MIME type of text/x-vCalendar. If you use iCalendar, the MIME type is "text/Calendar" and the extension is .ics.

Text/X-vCalendar Content Type
The vCalendar object can also be passed as a non-standard MIME media type. This would be useful in order to clearly identify the vCalendar object in an electronic mail message body part. A non-standard, vCalendar object should be identified as the MIME type/subtype "text/x-vCalendar".

@@ - i have to do some more investigation, but (i think) vCalendar is a subset of iCalendar, so many of the same encodings will work for both, but this document is dealing with iCalendar RFC2445 representation!

== Button ==

We need to come up with a nice <code>[ hCal | friendly ]</code> button to indicate that event info on a page/site is using hCalendar. - [http://tantek.com/log/ Tantek].

Possibilities:
* <code>[ hCal | friendly ]</code>
* <code>[ hCal | aware ]</code>
* <code>[ hCal | inside ]</code>
* <code>[ Valid | hCalendar ]</code> - though that would require writing an hCalendar validator which people could link to.
* <code>[ <icon> | hCalendar ]</code> where <icon> could be some generic calendar looking thing, or it could be a PHP generated image with the actual date in the icon, kind of like how the Apple iCal icon updates in the dock automatically.

And then we have to pick colors and all that stuff - [http://tantek.com/log/ Tantek].

Other ideas:
* <code>[ hCal | enabled ]</code>
* <code>[ hCal | available ]</code> - kind of an off-hand reference to being available for meetings, etc.

- [http://meyerweb.com/ Eric]

== Including More of iCalendar ==

=== Free/Busy information ===

See [http://www.ifreebusy.com/cyclical/blog/ Neil Jensen]'s [http://www.ifreebusy.com/cyclical/blog/calendar/3 analysis of how to represent the iCalendar VFREEBUSY object in hCalendar].

In order to show free/busy information, we could either use the existing vevent class (with empty location, summary, etc. properties) or create a new vfreebusy class. We should create a new vfreebusy class because it is consistent with the XHTML design principles, particularly point #4, "Use class names based on names from the original schema...".

In the iCalendar standard, the vfreebusy calendar component frequently has more than one freebusy property, and also may have a number of other properties such as organizer. For example:

<pre><nowiki>
BEGIN:VFREEBUSY
ORGANIZER:jsmith@host.com
DTSTART:19980313T141711Z
DTEND:19980410T141711Z
FREEBUSY:19980314T233000Z/19980315T003000Z
FREEBUSY:19980316T153000Z/19980316T163000Z
FREEBUSY:19980318T030000Z/19980318T040000Z
URL:http://www.host.com/calendar/busytime/jsmith.ifb
END:VFREEBUSY
</nowiki></pre>

So, our hCalendar representation should include separate elements for the vfreebusy calendar component (defined once) and the freebusy property (possibly defined many times):

<pre><nowiki>


<abbr class="dtstart" title="20050721T1000-0800">
July 21, 2005 - 10:00
</abbr> -
<abbr class="dtend" title="20050721T1100-0800">
11:00
</abbr>
 

<abbr class="dtstart" title="20050722T1000-0800">
July 22, 2005 - 10:00
</abbr> -
<abbr class="dtend" title="20050722T1100-0800">
11:00
</abbr>
 

</nowiki></pre>

According to RFC2445, "When publishing a "VFREEBUSY" calendar component, the property is used to specify the calendar that the published busy time came from." The property type is CAL-ADDRESS, and can include "non-standard, language, common name and directory entry reference" property parameters. CAL-ADDRESS is "...a URI as defined by [RFC 1738] or any other IANA registered form...".

From what I've seen, Microsoft Outlook typically populates this property with the email address of the calendar owner, which initially made me think of using hCard to specify the organizer. However, given that the property refers to the calendar and not necessarily the person who owns or has published it, I think we should use a new organizer element, as shown below:

<pre><nowiki>
BEGIN:VFREEBUSY
ORGANIZER:jsmith@host.com
FREEBUSY:20050314T133000Z/20050314T163000Z
END:VFREEBUSY
</nowiki></pre>

becomes

<pre><nowiki>

organizer: jsmith@host.com

<abbr class="dtstart" title="20050314T133000Z">
March 14, 2005 - 13:30
</abbr> -
<abbr class="dtend" title="20050314T163000Z">
16:30
</abbr>
 

</nowiki></pre>

Hmmm, this looks a little funny when the organizer is so obviously an email address, but at least it is semantically correct. The other problem that I can now see occurring is when the organizer property has parameters, for example (from the iCalendar spec):

<pre><nowiki>
ORGANIZER;CN=JohnSmith;DIR="ldap://host.com:6666/o=3DDC%20Associ
ates,c=3DUS??(cn=3DJohn%20Smith)":MAILTO:jsmith@host1.com
</nowiki></pre>

Perhaps it's best to use the same approach described in "Human vs. ISO8601 dates problem solved"; use the abbr element like so:

<pre><nowiki>


organizer: <abbr class="organizer" title="CN=JohnSmith;DIR=ldap://host.com:6666/o=3DDC%20Associ
ates,c=3DUS??(cn=3DJohn%20Smith):MAILTO:jsmith@host1.com">jsmith@host1.com</abbr>
<abbr class="dtstart" title="20050314T133000Z">
March 14, 2005 - 13:30
</abbr> -
<abbr class="dtend" title="20050314T163000Z">
16:30
</abbr>


</nowiki></pre>

=== To-Do information ===

The [http://www.policyawareweb.org/2005/ftf2/paw-mtg Policy Aware Web (PAW) Project Meeting - 23 Aug 2005] uses class="vtodo" to capture action items. Clearly recording action items from a meeting and publishing them as minutes is a good practical example use of the VTODO object on the web.

What's the scenario for usage though?

What kind of indexer/aggregator application would find these VTODO items and what would it do with them?

Perhaps with some way of figuring out who the to-do item is assigned to ("ATTENDEE"), who assigned it ("DELEGATED-FROM"), and a whitelisting of who, perhaps the "ORGANIZER" property, (and their domains/URLs) that a user would accept assignments from, a user could aggregate to-do items assigned from other folks. Then question remains how to update the status ("STATUS") (RFC 2445 4.8.1.11 Status) on that to-do item when it is (a) completed ("COMPLETED"), (b) abandoned/cut/rejected ("CANCELLED"), (c) some progress is made ("IN-PROCESS") etc. There certainly seems to be sufficient expressiveness in VTODO and its properties to do a decentralized to-do list / task distribution system. Could be very interesting for helping open source projects and other distributed teams do project management using the Web.

= References =
== Normative References ==
* [http://www.ietf.org/rfc/rfc2445.txt RFC 2445]
* [http://gmpg.org/xmdp/ XMDP]

== Informative References ==
* [http://wiki.oreillynet.com/foocamp04/index.cgi?HTMLForCalendars HTMLForCalendars (FOO camp)] - presented just a few days before this, hopefully these efforts can be combine

* [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]
* [http://www.ietf.org/rfc/rfc2446.txt iTIP RFC2446]
* [http://www.ietf.org/rfc/rfc2447.txt iMIP RFC2447]
* [http://www.ietf.org/rfc/rfc3283.txt Guide to Internet Calendaring RFC3283]

== Other Implementations/Ideas ==
* [http://www.nehmer.net/~bergie/openpsa-calendar-horizontal.jpg OpenPSA calendar screenshot]
* [http://www.w3.org/2002/12/cal/ RDF Calendar Workspace] - some older work done with RDF, not really applicable to the simple XHTML case, but perhaps worthy of analysis for when and why they may have diverged from established iCalendar schemas.
* [http://planb.nicecupoftea.org/archives/000072.html 2003 RDF icalendar work, xCal references]

== Blogs About Calendaring ==
* http://staff.washington.edu/oren/weblog2/

=Use in tables=
I currently have [http://www.westmidlandbirdclub.com/birmingham/field.htm events in table layout], using the format:
<pre><nowiki>
<tr class="X">
<th scope="row">Sunday 12 February 2006</th>
<td><a href="http://www.rspb.org.uk/reserves/guide/c/conwy/index.asp">RSPB Conwy</a>*/ Llanfairfechan.</td>
<td>A sea watch with potential for divers and sea ducks and a visit to a prime seaside reserve.</td>
</tr>
</nowiki></pre>

How would I include the code:
<pre><nowiki>
<div class="vevent">
<a class="url" href="http://www.westmidlandbirdclub.com/birmingham/field.htm">
<abbr class="dtstart" title="20060206">February 6 2006</abbr>
<abbr class="dtend" title="20060207"> </abbr>
Birmingham Branch Field Trip - at
RSPB Conwy/ Llanfairfechan.
</a>
<div class="description">A sea watch with potential for divers and sea ducks and a visit to a prime seaside reserve.</div>
</div>
</nowiki></pre>
in that? It seems to me that to loose the semantic table mark (column and row headers, for example) up would be a bad thing; not least for people whose lints don't understand hCal. Is the use of a non-breaking space in the dtend OK?[[User:PigsOTWing|PigsOTWing]] 12:12, 6 Feb 2006 (PST)

hcalendar-brainstorming

2006-02-06T20:12:38Z

PigsOTWing: Use in tables (my first edit!)

= hCalendar Brainstorming =
__TOC__
== Authors ==
* [http://suda.co.uk/ Brian Suda]
* [http://tantek.com/log/ Tantek Çelik]

= BEST-PRACTICES =
Along with the four base properties, you can define addtional properties through the use of the x-prop property. For best-practices for hCal to iCal transformers, it would be helpful if the transforming application added the following x-* properties:

* X-FROM-URL. The value of this property would be the URL of the page where the iCal representation was generated.
<pre><nowiki>
X-FROM-URL:http://example.com/page-containing-hCal-encoding.html
</nowiki></pre>

* X-WR-CALNAME. iCal.app recognizes this property as the "calendar name" for subscribed calendars. Thus transforming applications *should* take the <code><title>...</title></code> from the page being parsed, optionally append " events", and use that value for the X-WR-CALNAME property in the resulting feed. E.g. if the page had <code><title>Example Home Page</title></code> then the .ics output should have as part of the vcalendar object:
<pre><nowiki>
X-WR-CALNAME:Example Home Page
</nowiki></pre>

= Examples =
This is a growing example case written in iCal format and transformed to the corresponding XHTML. These conversions are open to community input.

<pre><nowiki>
BEGIN:VEVENT
CATEGORIES:foo,bar
SUMMARY: Short Title
DESCRIPTION: Full Description
DTSTART;VALUE=DATE:20040101
DTEND:20040101T235959Z
RRULE:FREQ=YEARLY;UNTIL=20080102T000000Z
URL;WORK:http://example.com
ATTENDEE;ROLE=CHAIR:MAILTO:JohnDoe@example.com
GEO:37.386013;-122.082932
END:VEVENT
</nowiki></pre>
<pre><nowiki>


Categories:
<ul class="categories">
<li>foo</li>
<li>bar</li>
</ul>
<a href="http://example.com" class="summary">Short Title</a>
description
37.386013 -122.082932



Date: 20040101 - 20040101T235959Z




<a class="attendee chair" href="mailto:JohnDoe@example.com">John Doe</a>


The event will be held yearly until 20080102T000000Z.


</nowiki></pre>

@@-need to look at nested tag examples
<pre><nowiki>
XHTML
Short Title to a longer article

vCal
SUMMARY:Short Title
DESCRIPTION:Short Title to a longer article
</nowiki></pre>

== Examples from RFC 2445 ==

* <del>Note: this subsection is worthy of being the start of a new page: [[hcalendar-examples]], similar to [[hcard-examples]] -[http://tantek.com/log/ Tantek]</del>
* These examples are now all available on [[hcalendar-examples]] -[[User:RyanKing]]

With the abbr's title attribute being used rather than the node value, the actual data could vary and still represent the same vcalendar.

<pre><nowiki>
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
DTSTART:19970714T170000Z
DTEND:19970715T035959Z
SUMMARY:Bastille Day Party
END:VEVENT
END:VCALENDAR
</nowiki></pre>

<pre><nowiki>


<abbr class="dtstart" title="19970714T170000Z">July 14th</abbr>
<abbr class="dtend" title="19970715T035959Z"></abbr>
Bastille Day Party


</nowiki></pre>

=== UID handling ===

The UID in iCal is represented in HTML as the id attribute in these examples. Any valid id in HTML is a valid UID in iCal, but not the contrapositive, a valid UID is NOT a valid HTML id. HTML ids can only start with a letter, not a number.

<pre><nowiki>
BEGIN:VEVENT
UID:19970901T130000Z-123401@host.com
DTSTAMP:19970901T1300Z
DTSTART:19970903T163000Z
DTEND:19970903T190000Z
SUMMARY:Annual Employee Review
CLASS:PRIVATE
CATEGORIES:BUSINESS,HUMAN RESOURCES
END:VEVENT
</nowiki></pre>

<pre><nowiki>


<abbr title="dtstamp" class="19970901T1300Z"></abbr>
<abbr title="dtstart" class="19970903T163000Z">September 3rd, 4:30pm</abbr>-
<abbr title="dtend" class="19970903T190000Z">7:00pm</abbr>
Annual Employee Review
private
<ul class="categories">
<li>BUSINESS</li>
<li>HUMAN RESOURCES</li>
</ul>


</nowiki></pre>

<pre><nowiki>
BEGIN:VCALENDAR
BEGIN:VEVENT
UID:19970901T130000Z-123402@host.com
DTSTAMP:19970901T1300Z
DTSTART:19970401T163000Z
DTEND:19970402T010000Z
SUMMARY:Laurel is in sensitivity awareness class.
CLASS:PUBLIC
CATEGORIES:BUSINESS,HUMAN RESOURCES
TRANSP:TRANSPARENT
END:VEVENT
END:VCALENDAR
</nowiki></pre>
<pre><nowiki>


<abbr title="dtstamp" class="19970901T1300Z"></abbr>
<abbr title="dtstart" class="19970401T163000Z">April 1st 4:30pm</abbr>-
<abbr title="dtend" class="19970402T010000Z">1:00am</abbr>
Laurel is in sensitivity awareness class.
PUBLIC
<ul class="categories">
<li>BUSINESS</li>
<li>HUMAN RESOURCES</li>
</ul>
Transparent


</nowiki></pre>

=== RRULE handling ===

The way RRULE is encoded should be discussed.

<pre><nowiki>
BEGIN:VEVENT
UID:19970901T130000Z-123403@host.com
DTSTAMP:19970901T1300Z
DTSTART:19971102
SUMMARY:Our Blissful Anniversary
CLASS:CONFIDENTIAL
CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION
RRULE:FREQ=YEARLY
END:VEVENT
</nowiki></pre>
<pre><nowiki>


<abbr title="dtstart" class="19970901T1300Z"></abbr>
<abbr title="dtend" class="19971102">November 2nd</abbr>
Our Blissful Anniversary
CONFIDENTIAL
<ul class="categories">
<li>ANNIVERSARY</li>
<li>PERSONAL</li>
<li>SPECIAL OCCASION</li>
</ul>
YEARLY


</nowiki></pre>

== Examples from real world event sites ==

=== W3C Meetings ===

I just got email announcing the dates of another W3C meeting. I don't think it's marked up with hCalendar. I could mark it up myself, like I did for [http://www.w3.org/2005/12/allgroupoverview.html the TP day/week schedule], but it might not stick. Somehow I got [http://www.w3.org/2000/08/w3c-synd/ our syndicated news markup] (precursor to [[hAtom]]) to stick, i.e. to become part of the norm in the W3C comm team. I wonder if I could pull that off for calendars.

My first thought is authoring tools, but I don't think I can wait that long.
Next thought is instant-feedback checking tools...
X2V is really handy, but can't be used for confidential pages (and many/most calendars I use are not public).
So.. how about some in-browser javascript "yes, you got it right!" or "hmm... that looks like a date; is there an event you didn't mark up?" feedback? I think I saw something like that in hCalendar implementations.

[[User:DanC|DanC]] 09:00, 3 Feb 2006 (PST)

=== Laughing Squid ===

Laughing Squid had the following [http://laughingsquid.com/squidlist/calendar/9584/2005/4/7 multiple occurence event example]:

Thu, Apr 7 : Tu/Wed: 12-4pm Th/Fr/Sat 12-7pm Sun 12-6pm

In addition, later on in the description, it says:

April 7-21, 2005

This is actually quite a non-trivial example, because the event lasts for different durations on different days (4 hours, 7 hours, 6 hours).

Because of the differing durations, the specification requires that *each* instance of this recurring event be explicitly specified.

But first we markup the starting date and time explicitly:
<pre>
<abbr class="dtstart" title="20050407T1200-0700">Thu, Apr 7</abbr> :
</pre>
Then we put in the quite lengthy explicit specification of every other time the event occurs, marked up around the human readable description.
<pre>
<abbr class="rdate" title="20050407T1200-0700/PT7H, 20050408T1200-0700/PT7H,
20050409T1200-0700/PT7H, 20050410T1200-0700/PT6H, 20050412T1200-0700/PT4H,
20050413T1200-0700/PT4H, 200504014T1200-0700/PT7H, 20050415T1200-0700/PT7H,
20050416T1200-0700/PT7H, 20050417T1200-0700/PT6H, 20050419T1200-0700/PT4H,
20050420T1200-0700/PT4H, 20050421T1200-0700/PT7H" >
Tu/Wed: 12-4pm Th/Fr/Sat 12-7pm Sun 12-6pm
</abbr>
</pre>

The RDATE "PERIOD" format is fairly straightforward. You simply list *each* occurrence of the event, separated by commas. Each occurrence consists of the ISO8601 datetime of the start of the event, followed by a slash "/", followed by *either* the duration of the event (e.g. 7 hours = PT7H), *or* a complete ISO8601 datetime of the end of the event. I chose to use the duration of the event for this example for reason of brevity.

Note that "value=period:" is unnecessary in the rdate value since the parser can infer "value=period:" from the presence of a "/" in the title attribute value.

With simpler repeating events, or perhaps events which only repeat a day or two, their hCalendar markup may be more illustrative of how to do this in a general way.

= CSS Styles =
Since the hCal properties are added in as CSS styles, you can style them along with any normal CSS style. You are free to style these properties in any fashion you want (see specific notes), but here are a few examples that you can use.

== Preserving White-space ==
If you are encoding data that requires tabs, returns, or other white-space to be perserved you can use the following CSS property to do so in HTML.
<pre><nowiki>

This white-space
will be
preserved

</nowiki></pre>
white-space can take one of three different parameters; normal, pre, and no-wrap.

== Not recommended ==

The following CSS styling techniques are not recommended:

=== Hiding Data ===
It is possible to encode additional data without it being displayed in the HTML, by using the CSS style property 'display'.
<pre><nowiki>
Hidden Data
</nowiki></pre>
This data will be found by any transforming application and will be properly encoded into an iCal file.

'''You SHOULD NOT do this because it violates the visibility priniciple.'''

= Tutorials =
How to include hCal encodings into your favourite Blogging Software.

= Open Questions =
== General Questions ==
Q: Should Transforming applications purely extract the information and ignore validity? or should there be some checking, or should this be left to the importing application? (i.e. DTSTART;VALUE=DATE: This-Is-Not-a-proper-date)

A: The simpler the better. Other than checking for perhaps X(HT)ML validity, it should be a simple translator, because presumably the receiving iCalendar application has to have malformed .ics handling already. Let's avoid duplicating that. -- [http://tantek.com/ Tantek Çelik]

Q: What about multiple of the instances same vCal entity? (two instances of DTSTART) Is this left up to the importing application, or should the XSLT transformation fail?

A: Same as previous. Leave it up to the importing application to interpret it per the iCalendar spec, e.g. what does RFC2445 say about two instances of DTSTART? -- [http://tantek.com/ Tantek Çelik]

From RFC2445:
4.1.2 Multiple Values
Some properties defined in the iCalendar object can have multiple values. The general rule for encoding multi-valued items is to simply create a new content line for each value, including the property name. However, it should be noted that some properties support encoding multiple values in a single property by separating the values with a COMMA character (US-ASCII decimal 44). Individual property definitions should be consulted for determining whether a specific property allows multiple values and in which of these two forms.

Other than that, it does not mention what to do ABOUT invalid data, or which of the multiple entries takes precedence. The only mention of duplicate instances is in the RRULE and EXDATE rules where events exclusions/inclusions overlap. Then duplicate instances are ignore. If it is explicitly written for those items, but NOT for things like DTSTART, then it is difficult to assume duplicate instances are ignored for them as well.

Each of the Components (VEVENT, ...) define which properties can exisit and in what quantity. So multiple DTSTART properties are NOT allowed.
-- [http://suda.co.uk Brian Suda]

Q: Should vCal entitles be represented in XHTML in classes ONLY on block-level element? or should some like VEVENT be block-level and others be of any? does this impact the semantics at all?

A: I don't think the (X)HTML notion of "block-level" should have any bearing whatsoever on vCal entities. You should be able to say or <div class="vevent"> and either should work.

Q: Should the transforming application add any additional information to the iCalendar representation other than what was encoded in the HTML? (i.e. UID, the unique identifier might not be present in the HTML code, but could be generated by the transforming application and added to the iCal file. Should this be allowed? or should the transforming app ONLY be allowed to add X-PROPERTY properties?) IF it was not explicitly encoded in the HTML should it be left out? What about default values?

Q: If we are looking at the most semantic way to encoding iCalendar data in HTML then several other attributes should be considered besides just 'class'. There are two other candidated, ID and REL. The ID tag MUST be unique within the XHTML file (this could be used for the UID property). The REL attribute can ONLY be applied to 'a' and 'link' tags, but might be helpful. Are namespac<ETH>H �n option? xml:lang, xml:base, are there any others that might be more semantically correct to encode this data?

Q: To help distinguish xparam values from other actual CSS styles, should we assume/mandate that all values in a class attribute within an encoded iCal component class attribute (<x class="vevent|vtodo|...">) be considered an xparam?

A: If you are using other CSS styles (e.g. "center", "bluebox", "greenline", etc.) nested within an iCal component, those should be avoided and the styles applied to the list of iCal properties instead/also?

<pre><nowiki>
.center, .vevent { text-align: center; }
</nowiki></pre>

Q: What about cases where the words "yesterday", "last year", or "last week" was used? How should we represent this? Is this overkill or not appropriate for hcard ? - [[User:B.K._DeLong]]

A: I took a stab at "yesterday" and just added a dtstart of the previous day. Not sure how to represent a single year or whole week - [[User:B.K._DeLong]]

<pre><nowiki>
<abbr class="dtstart" title="20050114">Yesterday's</abbr>
</nowiki></pre>

== Recurring Events ==

Recurring events are tricky. First, there's the question of whether to follow ''For types with multiple components, use nested elements with class names equivalent to the names of the components'' a la
<pre>
<nowiki><div class="rrule">every 1
WEEKLY on TU
until 2004-11-01</div></nowiki>
</pre>
... or ...
<pre>
<nowiki><abbr class="rrule" title="FREQ=WEEKLY;COUNT=17;INTERVAL=2;BYDAY=TH"> every other
Thursday for 34 weeks</abbr></nowiki>
</pre>
... as in [http://microformats.org/discuss/mail/microformats-discuss/2005-August/000516.html Tantek's 1 Aug msg].

[http://www.w3.org/People/Connolly/ DanC] has been experimenting with representing his PDA calendar in hCalendar:

* in [http://dev.w3.org/cvsweb/2001/palmagent/ palmagent], there's dangerSync.py which uses the XMLRPC interface and spits out RDF data. Then asHCal.xsl converts that to hCalendar
* then in [http://www.w3.org/2002/12/cal/ the RDF Calendar workspace], there's [http://www.w3.org/2002/12/cal/glean-hcal.xsl glean-hcal.xsl] that turns hCalendar into RDF Calendar, and finally,
* in [http://www.w3.org/2000/10/swap/ SWAP] there's [http://www.w3.org/2000/10/swap/pim/toIcal.py toIcal.py] that turns RDF Calendar to .ics format.

So I can go from my sidekick to .ics with one Makefile.

[http://dev.w3.org/cvsweb/2001/palmagent/event-test.html events-test.html] is a test file that has all the constructs from my PDA data, in hCalendar. In particular, it uses the nested element representation of recurring events. glean-hcal.xsl would be much less fun to write if it had to parse <nowiki>title="FREQ=WEEKLY;COUNT=17;INTERVAL=2;BYDAY=TH"</nowiki>.

Then there's the question of "every tuesday afternoon at 2pm Chicago time". This isn't expressible using [[datetime-design-pattern]]. There are some good reasons for that, but it leaves a rather large and uncomfortable gap in hCalendar.

== Encoding Questions ==
The way dates are encoded is not always the most user friendly. If i want to encode january 1st, 2005, that is <code>20050101</code>, which is displayed as 20050101. If we are marking-up comma seperated values, like FN, with each sub-element inside their own tag, then the date should be allowed the same.

(However, FN is in the RFC2426 spec and vCard schema, these individual date terms are not, therefore the reasoning in the last sentence is incorrect. -[http://tantek.com/log/ Tantek])

<pre><nowiki>
20050101
20050101
</nowiki></pre>
With this encoding, then YYYYMMDD schema can be rearranged for different cultures, DD-MM-YYYY for UK, MM-DD-YYYY for US, etc.
<pre><nowiki>
02-01-2005
02-01-2005
01-02-2005
01-02-2005
</nowiki></pre>
Both of the above encodings are equal, the '-' seperator is ignored by the transforming application. -- [http://suda.co.uk Brian Suda]

Agreed that the way dates are encoded is not always the most user friendly, but there is an easier solution to this, once you think of what is actually going on in the difference between ISO8601 dates, and dates the way humans use them. Humans typically use an abbrevation or shorthand for a date, like "tomorrow", or "Tuesday", or "the 4th", or perhaps "July 4th". Thus it makes sense to permit this in hCalendar, using the <code><abbr></code> tag which provides the ability to markup the human-familiar short form of some data or language, while preserving the long form in the 'title' attribute.

E.g. for the above example of a start date of January 1st, 2005, you could use this markup:

<pre><nowiki>
<abbr class="dtstart" title="20050101">January 1st, 2005</abbr>
</nowiki></pre>

Which would display as <code>January 1st, 2005</code> but would provide the respective ISO8601 date in the title attribute. - [http://tantek.com/log Tantek]

= TODO =
A HTML head profile needs creation and a home.

== Applications ==
A simple implementation of transforming/extracting vCal data from an XHTML file is available for testing. A bookmarklet is also available. The code will be updated as the spec is finalised.
http://suda.co.uk/projects/X2V/

== Parsing ==

Need to write up an [[hcalendar-parsing]] document, similar to [[hcard-parsing]].

=== Tabular Data ===

Many calendars are posted in tabular form, where the headings on the columns and rows have property values that apply to the cells which themselves are events.

(TODO: document "How To" for marking up tabular event listings)

To enable mark these up with [[hcalendar|hCalendar]], we must parse additional semantic attributes from HTML4.

When parsing, in addition to the special case rules documented in [[hcard-parsing]]:

* If the element is a table data cell <code><td></code>, then:
*# parse its "headers" attribute as a space separated set of local IDs
*# find the <code><td></code> and <code><th></code> elements referenced by those IDs (call them header cells) and consider them part of the element being parsed as follows:
*## Treat the header cells as children of the element, ordered by the order of ids in its "headers" attribute, immediately following the last child node (text or element) or the element. (The basic idea is that the content from those header cells is used to construct the VEVENT, but secondary to (AFTER) the content in the data cell itself, so that the data cell can customize/override part of the data in the header, e.g. if the header cell included both start time and location, and the event was being held at a different location).
*## Parse the "axis" attribute of a header cell as a comma-separated list of categories. These categories must be used in addition to (and before) any class names on that header cell for determining whether it is a property of the VEVENT.

== Relationships with other microformats ==

In a [http://www.technologyreview.com/articles/04/10/frauenfelder1004.asp Technology Review interview], TBL said "It would have the relationships between the event and the various people chairing it.".

We should have examples of how hCalendar events can indicate such relationships, both in the format and in the presentation.
E.g.:
* Would it just link to URLs for the various people? (e.g. to their homepages/blogs etc.)
* Would it include hCards for the various people?
* Would it link to hCards for various people?
* Perhaps allow all the above?

== Mime-Type ==
According to RFC2445, the proposed media type value is 'text/calendar'.

A standard vCalendar file has an extension of .vcs and MIME type of text/x-vCalendar. If you use iCalendar, the MIME type is "text/Calendar" and the extension is .ics.

Text/X-vCalendar Content Type
The vCalendar object can also be passed as a non-standard MIME media type. This would be useful in order to clearly identify the vCalendar object in an electronic mail message body part. A non-standard, vCalendar object should be identified as the MIME type/subtype "text/x-vCalendar".

@@ - i have to do some more investigation, but (i think) vCalendar is a subset of iCalendar, so many of the same encodings will work for both, but this document is dealing with iCalendar RFC2445 representation!

== Button ==

We need to come up with a nice <code>[ hCal | friendly ]</code> button to indicate that event info on a page/site is using hCalendar. - [http://tantek.com/log/ Tantek].

Possibilities:
* <code>[ hCal | friendly ]</code>
* <code>[ hCal | aware ]</code>
* <code>[ hCal | inside ]</code>
* <code>[ Valid | hCalendar ]</code> - though that would require writing an hCalendar validator which people could link to.
* <code>[ <icon> | hCalendar ]</code> where <icon> could be some generic calendar looking thing, or it could be a PHP generated image with the actual date in the icon, kind of like how the Apple iCal icon updates in the dock automatically.

And then we have to pick colors and all that stuff - [http://tantek.com/log/ Tantek].

Other ideas:
* <code>[ hCal | enabled ]</code>
* <code>[ hCal | available ]</code> - kind of an off-hand reference to being available for meetings, etc.

- [http://meyerweb.com/ Eric]

== Including More of iCalendar ==

=== Free/Busy information ===

See [http://www.ifreebusy.com/cyclical/blog/ Neil Jensen]'s [http://www.ifreebusy.com/cyclical/blog/calendar/3 analysis of how to represent the iCalendar VFREEBUSY object in hCalendar].

In order to show free/busy information, we could either use the existing vevent class (with empty location, summary, etc. properties) or create a new vfreebusy class. We should create a new vfreebusy class because it is consistent with the XHTML design principles, particularly point #4, "Use class names based on names from the original schema...".

In the iCalendar standard, the vfreebusy calendar component frequently has more than one freebusy property, and also may have a number of other properties such as organizer. For example:

<pre><nowiki>
BEGIN:VFREEBUSY
ORGANIZER:jsmith@host.com
DTSTART:19980313T141711Z
DTEND:19980410T141711Z
FREEBUSY:19980314T233000Z/19980315T003000Z
FREEBUSY:19980316T153000Z/19980316T163000Z
FREEBUSY:19980318T030000Z/19980318T040000Z
URL:http://www.host.com/calendar/busytime/jsmith.ifb
END:VFREEBUSY
</nowiki></pre>

So, our hCalendar representation should include separate elements for the vfreebusy calendar component (defined once) and the freebusy property (possibly defined many times):

<pre><nowiki>


<abbr class="dtstart" title="20050721T1000-0800">
July 21, 2005 - 10:00
</abbr> -
<abbr class="dtend" title="20050721T1100-0800">
11:00
</abbr>
 

<abbr class="dtstart" title="20050722T1000-0800">
July 22, 2005 - 10:00
</abbr> -
<abbr class="dtend" title="20050722T1100-0800">
11:00
</abbr>
 

</nowiki></pre>

According to RFC2445, "When publishing a "VFREEBUSY" calendar component, the property is used to specify the calendar that the published busy time came from." The property type is CAL-ADDRESS, and can include "non-standard, language, common name and directory entry reference" property parameters. CAL-ADDRESS is "...a URI as defined by [RFC 1738] or any other IANA registered form...".

From what I've seen, Microsoft Outlook typically populates this property with the email address of the calendar owner, which initially made me think of using hCard to specify the organizer. However, given that the property refers to the calendar and not necessarily the person who owns or has published it, I think we should use a new organizer element, as shown below:

<pre><nowiki>
BEGIN:VFREEBUSY
ORGANIZER:jsmith@host.com
FREEBUSY:20050314T133000Z/20050314T163000Z
END:VFREEBUSY
</nowiki></pre>

becomes

<pre><nowiki>

organizer: jsmith@host.com

<abbr class="dtstart" title="20050314T133000Z">
March 14, 2005 - 13:30
</abbr> -
<abbr class="dtend" title="20050314T163000Z">
16:30
</abbr>
 

</nowiki></pre>

Hmmm, this looks a little funny when the organizer is so obviously an email address, but at least it is semantically correct. The other problem that I can now see occurring is when the organizer property has parameters, for example (from the iCalendar spec):

<pre><nowiki>
ORGANIZER;CN=JohnSmith;DIR="ldap://host.com:6666/o=3DDC%20Associ
ates,c=3DUS??(cn=3DJohn%20Smith)":MAILTO:jsmith@host1.com
</nowiki></pre>

Perhaps it's best to use the same approach described in "Human vs. ISO8601 dates problem solved"; use the abbr element like so:

<pre><nowiki>


organizer: <abbr class="organizer" title="CN=JohnSmith;DIR=ldap://host.com:6666/o=3DDC%20Associ
ates,c=3DUS??(cn=3DJohn%20Smith):MAILTO:jsmith@host1.com">jsmith@host1.com</abbr>
<abbr class="dtstart" title="20050314T133000Z">
March 14, 2005 - 13:30
</abbr> -
<abbr class="dtend" title="20050314T163000Z">
16:30
</abbr>


</nowiki></pre>

=== To-Do information ===

The [http://www.policyawareweb.org/2005/ftf2/paw-mtg Policy Aware Web (PAW) Project Meeting - 23 Aug 2005] uses class="vtodo" to capture action items. Clearly recording action items from a meeting and publishing them as minutes is a good practical example use of the VTODO object on the web.

What's the scenario for usage though?

What kind of indexer/aggregator application would find these VTODO items and what would it do with them?

Perhaps with some way of figuring out who the to-do item is assigned to ("ATTENDEE"), who assigned it ("DELEGATED-FROM"), and a whitelisting of who, perhaps the "ORGANIZER" property, (and their domains/URLs) that a user would accept assignments from, a user could aggregate to-do items assigned from other folks. Then question remains how to update the status ("STATUS") (RFC 2445 4.8.1.11 Status) on that to-do item when it is (a) completed ("COMPLETED"), (b) abandoned/cut/rejected ("CANCELLED"), (c) some progress is made ("IN-PROCESS") etc. There certainly seems to be sufficient expressiveness in VTODO and its properties to do a decentralized to-do list / task distribution system. Could be very interesting for helping open source projects and other distributed teams do project management using the Web.

= References =
== Normative References ==
* [http://www.ietf.org/rfc/rfc2445.txt RFC 2445]
* [http://gmpg.org/xmdp/ XMDP]

== Informative References ==
* [http://wiki.oreillynet.com/foocamp04/index.cgi?HTMLForCalendars HTMLForCalendars (FOO camp)] - presented just a few days before this, hopefully these efforts can be combine

* [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]
* [http://www.ietf.org/rfc/rfc2446.txt iTIP RFC2446]
* [http://www.ietf.org/rfc/rfc2447.txt iMIP RFC2447]
* [http://www.ietf.org/rfc/rfc3283.txt Guide to Internet Calendaring RFC3283]

== Other Implementations/Ideas ==
* [http://www.nehmer.net/~bergie/openpsa-calendar-horizontal.jpg OpenPSA calendar screenshot]
* [http://www.w3.org/2002/12/cal/ RDF Calendar Workspace] - some older work done with RDF, not really applicable to the simple XHTML case, but perhaps worthy of analysis for when and why they may have diverged from established iCalendar schemas.
* [http://planb.nicecupoftea.org/archives/000072.html 2003 RDF icalendar work, xCal references]

== Blogs About Calendaring ==
* http://staff.washington.edu/oren/weblog2/

==Use in tables==
I currently have [http://www.westmidlandbirdclub.com/birmingham/field.htm events in table layout], using the format:
<pre><nowiki>
<tr class="X">
<th scope="row">Sunday 12 February 2006</th>
<td><a href="http://www.rspb.org.uk/reserves/guide/c/conwy/index.asp">RSPB Conwy</a>*/ Llanfairfechan.</td>
<td>A sea watch with potential for divers and sea ducks and a visit to a prime seaside reserve.</td>
</tr>
</nowiki></pre>

How would I include the code:
<pre><nowiki>
<div class="vevent">
<a class="url" href="http://www.westmidlandbirdclub.com/birmingham/field.htm">
<abbr class="dtstart" title="20060206">February 6 2006</abbr>
<abbr class="dtend" title="20060207"> </abbr>
Birmingham Branch Field Trip - at
RSPB Conwy/ Llanfairfechan.
</a>
<div class="description">A sea watch with potential for divers and sea ducks and a visit to a prime seaside reserve.</div>
</div>
</nowiki></pre>
in that? It seems to me that to loose the semantic table mark (column and row headers, for example) up would be a bad thing; not least for people whose lints don't understand hCal. Is the use of a non-breaking space in the dtend OK?[[User:PigsOTWing|PigsOTWing]] 12:12, 6 Feb 2006 (PST)