dtend-issue

From Microformats Wiki
Revision as of 01:36, 6 March 2010 by Tantek (talk | contribs) (→‎summary: update summary to reflect summary of resolution of issue, and update original issue summary with past tense and more explanatory language.)
Jump to navigation Jump to search

<entry-title>dtend-issue</entry-title> An hCalendar issue.

shortlink
http://tr.im/dtendi

summary

Authors typically publish the end date of a multi-day event as the last day the event occurs. This is called an inclusive end date.

Unfortunately the iCalendar standard requires publishing the day *after* the the last day of a multi-day event. This is called an exclusive end date.

As a result of this (the dtend) issue, hCalendar now supports the more user/author-friendly inclusive end dates / dtend property values, and hCalendar to iCalendar converters MUST automatically convert such inclusive hCalendar end date (dtend) property values to the equivalent exclusive iCalendar DTEND property values.

E.g. this dtend inside an hCalendar event: 

<span class="dtend">2010-03-16</span>

is treated inclusively as people expect the content to mean, that is the event *includes* and ends on March 16th, and it MUST be translated by hCal-to-iCal converters to the following in iCalendar: 

DTEND:20100317

original issue summary

The original (old) hCalendar draft required that end *dates* be marked up as occuring a whole day after what people typically consider the end date of an event.

E.g. if a conference starts on 2010 March 12th and ends 2010 March 16th, then the dtend was marked up with the value of "2010-03-17" - seemingly a whole day after the end of the conference. hCalendar suggested obscuring this disparity between the human visible end date and the machine specified date using the <abbr> tag:

OBSOLETE EXAMPLE FOR ILLUSTRATION PURPOSES ONLY: 

<div class="vevent">
 <span class="summary">a conference</span>
 starts on <span class="dtstart">2010-03-12</span>, and
 ends on <abbr class="dtend" title="2010-03-17">2010-03-16</abbr>.
</div>

This is due to hCalendar's dtend property being originally specified with the same semantics as iCalendar's DTEND property, which places that requirement on the DTEND property of the VEVENT object.

Unfortunately this turned out to be very problematic:

  • in practice authors have published inclusive dtend values
  • the use of abbr required a particularly bad form of DRY violation.
  • the use of abbr to present two seemingly different values appeared to be a bug upon casual review and was often (then errantly) "fixed" to be consistent, or simply replaced with a span with a single inline text value.

Thus this issue was raised, discussed, and resolved accordingly.

hCalendar has an inclusive dtend property for whole days.

iCalendar has an exclusive DTEND property for whole days.

The burden of handling this difference is place upon hCalendar-to-iCalendar converters, rather than content authors and publishers, per the principle of humans (authors) first, parsers (machines) second.

problems

This is problematic for several reasons:

  • Appears inconsistent. It is odd that the value specified for machine consumption is different than the value specified for human consumption - regardless of format/syntax - and appears inconsistent to anyone who sees the tooltip, or views and copy/pastes the source. It looks like a bug or mistake, and in fact has been errantly "corrected" as such (e.g. even in the hCalendar spec itself).
  • Unintuitive for authoring. When authors are writing up the end date for an event, they write up what a human expects to see - the last day of the event. It is an unintuitive leap to think to specify +1 day for machine consumption, and an additional cognitive load (in order to get it right).
  • Semantic abuse of abbr. An abbr's title attribute provides an expansion for the inner text. In no way is a +1 date an expansion of a date, it appears more like a completely different value.
  • Required DRY violation. While the dtstart in the above example is specified only once, readable to both humans and machines, the dtend must be specified twice, once for humans, and once for machines, thus requiring a particularly bad DRY (Don't Repeat Yourself) violation, that of requiring data be specified twice, but slightly different in one instance than another, thus increasing the chances of duplication based errors even more (since verifiability is more difficult).
    • Prevents use of simple markup As a result of the forced DRY violation, it is not possible to use simple markup like <span class="dtend">2010-03-16</span> because while a human reads that as an event that ends on the 16th, an hCalendar 1.0 processor will read that as an event that ended the day before, on the 15th.

possible solutions

As noted in the issue description on the hCalendar issues page, there are at least a couple of possible solutions.

dtend inclusive whole dates

resolved issue

  • redefine hCalendar 1.0.1 dtend to be inclusive for whole dates.
    • Advantage: Zero impact on vocabulary.
    • Advantage: No increase to hCalendar authoring complexity.
    • Advantage: Will reflect dominant use of dtend in examples in the wild (more research and citations needed to back this up!). In other words, authors have ALREADY been using dtend assuming it works this way (inclusive end dates), and will actually be surprised to find out that it doesn't. Making this change to DTEND semantics may actually reflect hCalendar publishing reality more than keeping the precise iCalendar DTEND semantic. Examples of inclusive dtend usage in the wild:
      • http://barcamp.org/ - BarCamp wiki, dates for BarCamps
      • microformats.org/wiki/events/ - several multi-day event listings, as recently as Glenn Jones (who himself is a very knowledgable and prolific microformats developer) event page for SXSW 2010 use inclusive DTENDs (notably, using a span element that does NOT duplicate content).
      • draft of Emily Lewis' book Microformats Made Simple, uses dtend for inclusive end dates.
      • microformats.org co-founder and expert Dan Cederholm's SimpleBits home page has an events calendar that uses inclusive dtend dates.
      • http://upcoming.org (apparently - according to Michael Kaply)
      • ... more instances of existing use of DTEND for *inclusive* end dates.
    • Advantage: Some number of implementations treat DTEND dates as *inclusive* (technically these are violating the current hCalendar spec, but they may be doing so deliberately to reflect actual hCalendar publishing practices). Implementations
    • ... any other advantages?
    • Disadvantage: Redefines DTEND to be *slightly* different from how it is defined in iCalendar. This may lead to errors on the part of developers.
      • Mitigation: it may be possible to mitigate this disadvantage by providing both very precise hCalendar to iCalendar processor conformance requirements, and sufficient test cases for hCalendar to iCalendar processors for them to get this correct in their code.
    • Disadvantage: breaking some amount of existing hCalendar content on the web (research needed to determine the extent of the problem)
      • Workarounds: Based on aforementioned research, workarounds may be possible, e.g. heuristics for when abbr is used similar to the example at the top of the page, to detect "off by one" cases and accommodate accordingly). Make it an explicit error for the human visible date to be different than the machine parsed date, and state specific error handling rules for hCalendar processors that "repair" this problem.
    • ... any other disadvantages?
    • Opinions:
      • +1 Based on the fact that this problem just hasn't gone away, and that people (smart knowledgable people!) continue to treat "dtend" end dates *inclusively*, I now think it makes more sense (and is more practical) to change the spec to be consistent with the dominant expectation of web authors, rather than continue attempting to change the expectations of web authors to be consistent with the spec. I think this is the simplest, most effective, and least risky option. Tantek
      • +1 This appears logical and intuitive. We are effectively saying that end dates such as DTEND should parse to YYYY-MM-DDT24:00:00, and not YYYY-MM-DDT00:00:00. Seems simple, and entirely logical from a publishing stand —BenWard 08:18, 27 August 2009 (UTC)
      • +1 The spec should reflect the intuitive publishing behaviour (inclusive end dates). Humans first. —Jeremy Keith
      • +1 Though I'm worried about tools catching up to this change. Ted
      • +1 The natural human way to think about dates is inclusively; if the dtend date and dtstart date are equal, that clearly doesn't imply zero duration. The microformats principle of making things easier for authors rather than parser writers wins here Kevin Marks
      • +1 It is much easier to migrate the limited number of tools and authors who already grok hCalendar 1.0 than to migrate publisher intuition. MatthewLevine
      • +1 I agree with MatthewLevine. Those who follow hCalendar development are likely to make the change to inclusive dates, and those who don't are likely using inclusive dates already. Chris Cressman
      • ... please add your +1/0/-1 opinion here and sign with three tildas (~~~)

inclusive dtend test cases

Test case(s) that check for the implementation of this issue resolution:

new end dates property

  • new hCalendar 1.0.1 property for end dates. As noted in the first resolution of the issue, we could introduce a new property, dtlast (described more in hCalendar brainstorming: dtlast) which authors would use to specify the last day of an event, instead of dtend.
    • Advantage: Maintains iCalendar conceptual compatibility for DTEND values.
    • Advantage: Compatibility with existing hCalendar 1.0 content that just happened to get the end date +1 distinction right.
    • ... any other advantages?
    • Disadvantage: Increased vocabulary. dtlast is a new term, even if it is not new functionality. Essentially this puts additional burden on authors.
    • Disadvantage: Increased complexity/confusion. When to use dtend vs. dtlast? hCalendar authors would now have to remember, use dtend for end *times* and dtlast for end *dates*. More explanation of the additional burden on authors.
    • ... any other disadvantages?
    • Opinions:
      • -1 despite originally proposing this solution, I now think an additional term, and rule for when to use the new term vs. the old term will actually make this problem worse and more confusing to web authors. Tantek
      • ... please add your +1/0/-1 opinion here and sign with three tildas (~~~)

other

  • ... other possible solutions?

origins

This issue was raised to me (Tantek) in person pretty much since the first time I gave such an example back in 2004, was something I had to explicitly cover and point out in nearly every microformats presentation I gave, was eventually pointed out on the microformats discuss mailing list (citation needed), and eventually explicitly documented as an issue on the wiki hcalendar-issues page by Andy Mabbett on 2007-01-20.

see also

Retrieved from "http://microformats.org/wiki/index.php?title=dtend-issue&oldid=42124"