1.1 --- a/docs/wiki/EventRecurrences Mon Oct 26 13:49:51 2015 +0100
1.2 +++ b/docs/wiki/EventRecurrences Mon Oct 26 14:05:25 2015 +0100
1.3 @@ -1,36 +1,99 @@
1.4 = Event Recurrences =
1.5
1.6 -Events defined by iCalendar objects may recur when [[http://tools.ietf.org/html/rfc5545#section-3.8.5|recurrence component properties]] such as `RDATE` and `RRULE` are employed. Each recurrence of an event may then be referenced using [[http://tools.ietf.org/html/rfc5545#section-3.8.4.4|recurrence identifiers]], and such identifiers indicate the originally-specified start point of a particular recurrence (either implicitly specified by `RRULE` properties or explicitly specified by `RDATE` properties).
1.7 +Events defined by iCalendar objects may recur when
1.8 +[[http://tools.ietf.org/html/rfc5545#section-3.8.5|recurrence component properties]]
1.9 +such as `RDATE` and `RRULE` are employed. Each recurrence of an event may then
1.10 +be referenced using
1.11 +[[http://tools.ietf.org/html/rfc5545#section-3.8.4.4|recurrence identifiers]],
1.12 +and such identifiers indicate the originally-specified start point of a
1.13 +particular recurrence (either implicitly specified by `RRULE` properties or
1.14 +explicitly specified by `RDATE` properties).
1.15
1.16 == Recurrence Identifier Stability ==
1.17
1.18 -A recurrence retains the same identifier throughout its lifetime. Even if a recurrence's start date or time changes, it will still retain the same identifier in its `RECURRENCE-ID` property which will no longer reflect the currently-specified start point of the recurrence. Such identifier stability is intended to provide a means of identifying the original recurrence so that it can be hidden from any calendar or event descriptions and replaced with the modified version.
1.19 +A recurrence retains the same identifier throughout its lifetime. Even if a
1.20 +recurrence's start date or time changes, it will still retain the same
1.21 +identifier in its `RECURRENCE-ID` property which will no longer reflect the
1.22 +currently-specified start point of the recurrence. Such identifier stability
1.23 +is intended to provide a means of identifying the original recurrence so that
1.24 +it can be hidden from any calendar or event descriptions and replaced with the
1.25 +modified version.
1.26
1.27 == Recurrences and Time Zones ==
1.28
1.29 -Since recurrence identifiers may be defined using time zone information, imip-agent normalises the specified recurrence identifiers to UTC-based datetimes to minimise ambiguity. For example:
1.30 +Since recurrence identifiers may be defined using time zone information,
1.31 +imip-agent normalises the specified recurrence identifiers to UTC-based
1.32 +datetimes to minimise ambiguity. For example:
1.33 +
1.34 +|| '''iCalendar Property''' || '''Normalised Value''' || '''UTC Datetime?''' ||
1.35 +|| `RECURRENCE-ID:20141114` || `20141114` || No ||
1.36 +|| `RECURRENCE-ID:20141114T000000` || `20141114T000000` || No ||
1.37 +|| `RECURRENCE-ID;TZID=Europe/Oslo:20141114` || `20141113T230000Z` || Yes ||
1.38 +|| `RECURRENCE-ID;TZID=Europe/Oslo:20141114T000000` || `20141113T230000Z` || Yes ||
1.39 +|| `RECURRENCE-ID:20141114T000000Z` || `20141114T000000Z` || Yes ||
1.40
1.41 -|| '''iCalendar Property''' || '''Normalised Value''' || '''UTC Datetime?''' ||
1.42 -|| `RECURRENCE-ID:20141114` || `20141114` || No ||
1.43 -|| `RECURRENCE-ID:20141114T000000` || `20141114T000000` || No ||
1.44 -|| `RECURRENCE-ID;TZID=Europe/Oslo:20141114` || `20141113T230000Z` || Yes ||
1.45 -|| `RECURRENCE-ID;TZID=Europe/Oslo:20141114T000000` || `20141113T230000Z` || Yes ||
1.46 -|| `RECURRENCE-ID:20141114T000000Z` || `20141114T000000Z` || Yes ||
1.47 +Identifiers without time zone information are not in themselves sufficient to
1.48 +unambiguously define points in time, and thus additional time zone information
1.49 +must be provided to obtain such time periods for such purposes as detecting
1.50 +conflicts with other events. In the above examples, those normalised values
1.51 +not providing a UTC datetime representation need further conversion to be
1.52 +usable for period comparisons. Such further conversion would be done by
1.53 +nominating a disambiguating time zone, such as the user's configured time
1.54 +zone.
1.55
1.56 -Identifiers without time zone information are not in themselves sufficient to unambiguously define points in time, and thus additional time zone information must be provided to obtain such time periods for such purposes as detecting conflicts with other events. In the above examples, those normalised values not providing a UTC datetime representation need further conversion to be usable for period comparisons. Such further conversion would be done by nominating a disambiguating time zone, such as the user's configured time zone.
1.57 +By normalising identifiers using any object-resident time zone information,
1.58 +imip-agent can use the resulting values without needing to consult the object
1.59 +providing any redefined recurrence, knowing that any time zone information has
1.60 +already been taken into consideration. Thus, all UTC-based datetimes used as
1.61 +recurrence identifiers are readily usable for comparison purposes, whereas any
1.62 +floating date or datetime values used as recurrence identifiers must need
1.63 +additional conversion using the user's time zone to be usable.
1.64
1.65 -By normalising identifiers using any object-resident time zone information, imip-agent can use the resulting values without needing to consult the object providing any redefined recurrence, knowing that any time zone information has already been taken into consideration. Thus, all UTC-based datetimes used as recurrence identifiers are readily usable for comparison purposes, whereas any floating date or datetime values used as recurrence identifiers must need additional conversion using the user's time zone to be usable.
1.66 -
1.67 -It might be thought that there would be correspondence between a recurrence identifier and the time zone details employed by the original object describing the redefined recurrence (such as the `TZID` attribute specified on an object's `DTSTART` property), and so any unqualified recurrence identifier might be converted to a UTC-based datetime using such time zone details. However, an assumption could equally be made that the recurrence identifier should inherit time zone details from the redefined recurrence instead. The only reasonable choice to be made when confronted with such ambiguity is to treat any unqualified identifier as a genuine floating date or datetime, and the normalisation process facilitates this strategy.
1.68 +It might be thought that there would be correspondence between a recurrence
1.69 +identifier and the time zone details employed by the original object
1.70 +describing the redefined recurrence (such as the `TZID` attribute specified on
1.71 +an object's `DTSTART` property), and so any unqualified recurrence identifier
1.72 +might be converted to a UTC-based datetime using such time zone details.
1.73 +However, an assumption could equally be made that the recurrence identifier
1.74 +should inherit time zone details from the redefined recurrence instead. The
1.75 +only reasonable choice to be made when confronted with such ambiguity is to
1.76 +treat any unqualified identifier as a genuine floating date or datetime, and
1.77 +the normalisation process facilitates this strategy.
1.78
1.79 == Recurrences and Free/Busy Information ==
1.80
1.81 -Events employing recurrences on fixed occasions can be readily recorded in the free/busy information for a calendar user. However, iCalendar also permits recurrences that may potentially continue forever, and yet providing free/busy information for arbitrary periods in the future may either result in substantial computation or substantial demands on storage resources. Consequently, free/busy information may only be generated for a period ending at a certain point in the future defined in terms of days from the present. Within this period scheduling would make sense, and attempts to schedule events outside this period would succeed at the participant's own risk.
1.82 +Events employing recurrences on fixed occasions can be readily recorded in the
1.83 +free/busy information for a calendar user. However, iCalendar also permits
1.84 +recurrences that may potentially continue forever, and yet providing free/busy
1.85 +information for arbitrary periods in the future may either result in
1.86 +substantial computation or substantial demands on storage resources.
1.87 +Consequently, free/busy information may only be generated for a period ending
1.88 +at a certain point in the future defined in terms of days from the present.
1.89 +Within this period scheduling would make sense, and attempts to schedule
1.90 +events outside this period would succeed at the participant's own risk.
1.91
1.92 -Such a period where participant availability is known must be necessarily expanded as time progresses. One-off events, once recorded in the free/busy records, will not contribute further to expansions of those records. Recurring events, however, may provide additional periods of interest as the availability window moves forward in time.
1.93 +Such a period where participant availability is known must be necessarily
1.94 +expanded as time progresses. One-off events, once recorded in the free/busy
1.95 +records, will not contribute further to expansions of those records. Recurring
1.96 +events, however, may provide additional periods of interest as the
1.97 +availability window moves forward in time.
1.98
1.99 -To determine which events contribute recurrences, a list of objects (initially all objects known to a user that have not been cancelled) is consulted and their recurrence properties inspected. With such knowledge of recurring events, upon expanding the availability window, only these "known recurring" events need to be inspected for further contributions to the free/busy records, and those no longer contributing after a given point can be discarded from the list for future expansion of the window. Meanwhile, new events would need to be added to the list, at least if they were defined as providing recurrences that may occur in future availability periods.
1.100 +To determine which events contribute recurrences, a list of objects (initially
1.101 +all objects known to a user that have not been cancelled) is consulted and
1.102 +their recurrence properties inspected. With such knowledge of recurring
1.103 +events, upon expanding the availability window, only these "known recurring"
1.104 +events need to be inspected for further contributions to the free/busy
1.105 +records, and those no longer contributing after a given point can be discarded
1.106 +from the list for future expansion of the window. Meanwhile, new events would
1.107 +need to be added to the list, at least if they were defined as providing
1.108 +recurrences that may occur in future availability periods.
1.109
1.110 === Updating Free/Busy Records ===
1.111
1.112 -To update and thus expand availability information, it is suggested that a regularly scheduled task be used to consult the events known (or thought) to provide additional free/busy periods and to record such additional periods for each user. This can be done using a system's `cron` daemon and a suitable script in `/etc/cron.daily` or equivalent. Such a script is provided in the imip-agent distribution along with a program that can expand availability information for all known recipients of calendar information.
1.113 +To update and thus expand availability information, it is suggested that a
1.114 +regularly scheduled task be used to consult the events known (or thought) to
1.115 +provide additional free/busy periods and to record such additional periods for
1.116 +each user. This can be done using a system's `cron` daemon and a suitable
1.117 +script in `/etc/cron.daily` or equivalent. Such a script is provided in the
1.118 +imip-agent distribution along with a program that can expand availability
1.119 +information for all known recipients of calendar information.