Subject: [Ietf-calsify] Proposal for issue 11

From: cyrus at daboo.name (Cyrus Daboo)
Date: Thu May 24 07:27:04 2007

Hi,
Re: <http://www.ofcourseimright.com/cgi-bin/roundup/calsify/issue11>.

The proposal to close this is to add the attached table on recurrence part 
behavior to the draft. Plus there would be some text revisions to reference 
the table at appropriate places.

Please review the attached table - Bernard will likely be adding it to the 
draft for the next revision.

-- 
Cyrus Daboo
-------------- next part --------------
RRULE Processing

A particular BYxxx rule part may expand or limit the set of date/times 
generated by the rule. The expand or limit behaviour is governed by the 
FREQ value used for the rule.

Example:

	RRULE:FREQ=MONTHLY;BYMONTH=1,3,5;BYDAY=MO,TU

		The FREQ=MONTHLY value would match each of the twelve
		months in a year.

		The BYMONTH=1,3,5 rule part limits the matching months to just
		the 1st, 3rd and 5th in a year.

		The BYDAY=MO,TU rule part adds each Monday and Tuesday within
		the matching months to the recurrence set.

The table below shows the dependency of BYxxx rule part expand or limit 
behaviour on the FREQ value in the rule. When evaluating a rule, each BYxxx 
rule part must be evaluated in the order it appears in the table (i.e. 
BYMONTH evaluated before BYWEEKNO), irrespective of the expand or limit 
behaviour.

BYDAY has some special behaviour depending on the FREQ value and this is 
described in separate notes below the table.

+--------------------------------------------------------------------------+
|          |SECONDLY|MINUTELY| HOURLY | DAILY  | WEEKLY | MONTHLY | YEARLY |
|----------+--------+--------+--------+--------+--------+---------+--------|
|BYMONTH   | Limit  | Limit  | Limit  | Limit  | Limit  | Limit   | Expand |
|----------+--------+--------+--------+--------+--------+---------+--------|
|BYWEEKNO  | Limit  | Limit  | Limit  | Limit  | Limit  | N/A     | Expand |
|----------+--------+--------+--------+--------+--------+---------+--------|
|BYYEARDAY | N/A    | N/A    | N/A    | N/A    | N/A    | N/A     | Expand |
|----------+--------+--------+--------+--------+--------+---------+--------|
|BYMONTHDAY| Limit  | Limit  | Limit  | Limit  | N/A    | Expand  | Expand |
|----------+--------+--------+--------+--------+--------+---------+--------|
|BYDAY     | Limit  | Limit  | Limit  | Limit  | Note 1 | Note 2  | Note 3 |
|----------+--------+--------+--------+--------+--------+---------+--------|
|BYHOUR    | Limit  | Limit  | Limit  | Expand | Expand | Expand  | Expand |
|----------+--------+--------+--------+--------+--------+---------+--------|
|BYMINUTE  | Limit  | Limit  | Expand | Expand | Expand | Expand  | Expand |
|----------+--------+--------+--------+--------+--------+---------+--------|
|BYSECOND  | Limit  | Expand | Expand | Expand | Expand | Expand  | Expand |
|----------+--------+--------+--------+--------+--------+---------+--------|
|BYSETPOS  | Limit  | Limit  | Limit  | Limit  | Limit  | Limit   | Limit  |
+----------+--------+--------+--------+--------+--------+---------+--------+

+--------------------------------------------------------------------+
| Note 1 | Special expand for WEEKLY.                                |
|        |                                                           |
|        | A BYDAY rule part cannot have a numeric value in a        |
|        | FREQ=WEEKLY rule (i.e. 'MO', 'TU' etc is allowed, but     |
|        | '1MO', '2TU' is not allowed).                             |
|        |                                                           |
+--------+-----------------------------------------------------------|
| Note 2 | Limit if BYYEARDAY or BYMONTHDAY is present,              |
|        | otherwise special expand for MONTHLY.                     |
|        |                                                           |
|        | The numeric value in a BYDAY rule part in a FREQ=MONTHLY  |
|        | rule corresponds to an offset with the month.             |
|        |                                                           |
+--------+-----------------------------------------------------------|
| Note 3 | Limit if BYYEARDAY or BYMONTHDAY is present,              |
|        | otherwise special expand for WEEKLY if BYWEEKNO present,  |
|        | otherwise special expand for MONTHLY if BYMONTH present,  |
|        | otherwise special expand for YEARLY.                      |
|        |                                                           |
|        | A BYDAY rule part cannot have a numeric value in a        |
|        | FREQ=YEARLY rule (i.e. 'MO', 'TU' etc is allowed, but     |
|        | '1MO', '2TU' is not allowed), if BYWEEKNO is specified.   |
|        |                                                           |
|        | The numeric value in a BYDAY rule part in a FREQ=YEARLY   |
|        | rule with a BYMONTH present corresponds to an offset with |
|        | the month.                                                |
|        |                                                           |
|        | The numeric value in a BYDAY rule part in a FREQ=YEARLY   |
|        | rule without BYWEEKNO or BYMONTH present corresponds to   |
|        | an offset within the year.                                |
|        |                                                           |
+--------+-----------------------------------------------------------+

---

From: Nigel.Swinson at rockliffe.com (Nigel Swinson)
Date: Tue May 29 13:54:17 2007

> draft for the next revision.

I found the table very useful in explaining the whole Limit/Expand nature of the modifiers, but found all the notes on BYDAY very complex and discouraging.  I also finally got round to reading Claudio's comments, and of the 4, thought he only had one lengthy/major one, which related to the complexity of BYXX processing.  While adding the table will help, on closer inspection I think I've found inconsistencies when read with the spec that have led to the following comments: 

- Note 1 implies that a numeric value is not allowed if the FREQ is WEEKLY, whereas it is currently left very vague in the spec.  If this is to be true, then it should be dissallowed for SECONDLY/MINUTELY/HOURLY/DAILY too and stated explicitly in the spec.  The alternative is we just ignore the numeric value should the interval be a week or less, but I think it's better to dissallow.  I suggest:

      Each BYDAY value can also be preceded by a positive (+n) or
-      negative (-n) integer.  If present, this indicates the nth
-      occurrence of the specific day within the MONTHLY or YEARLY
-      "RRULE".  For example, within a MONTHLY rule, +1MO (or simply 1MO)
+      negative (-n) integer modifer.  These are only valid for MONTHLY
+      or YEARLY rules.  When present, they indicates the nth
+      occurrence of the specific day within the month or year.
+      For example, within a MONTHLY rule, +1MO (or simply 1MO)
      represents the first Monday within the month, whereas -1MO
      represents the last Monday of the month.  If an integer modifier
      is not present, it means all days of this type within the
      specified frequency.  For example, within a MONTHLY rule, MO
      represents all Mondays within the month.

- In Note 3 it says the numeric value might be an offset into the month or the year.  I think this is an unhelpful, unintuative special case that contradicts the spec, and would rather the numeric value in a YEARLY rule is always the offset within the year.

- In Note 2 it implies that MONTHLY + BYDAY + BYYEARDAY needs to be considered, but in the MONTHLY + BYYEARDAY entry in the table it says N/A.   In fact it says that BYYEARDAY is only valid with YEARLY rules when no such restriction exists in the spec.  I think it's a helpful restriction to reduce complexity and ambiguity, but wouldn't go so far as to disallow with SECONDLY/MINUTELY/HOURLY/DAILY/WEEKLY, so I suggest:

      The BYYEARDAY rule part specifies a COMMA character (US-ASCII
      decimal 44) separated list of days of the year.  Valid values are
      1 to 366 or -366 to -1.  For example, -1 represents the last day
      of the year (December 31st) and -306 represents the 306th to the
-      last day of the year (March 1st).
+      last day of the year (March 1st).  This rule part is not valid
+      for WEEKLY or MONTHLY rules.

- The table implies WEEKLY + BYMONTHDAY is not allowed, but this isn't in the spec.  I think this is a helpful restriction, as either you are taking a month based view of life or a week based view of life, and the restriction reduces complexity and ambiguity.  I suggest the restriction is added by:

      The BYMONTHDAY rule part specifies a COMMA character (US-ASCII
      decimal 44) separated list of days of the month.  Valid values are
      1 to 31 or -31 to -1.  For example, -10 represents the tenth to
-      the last day of the month.
+      the last day of the month.  This rule part is not valid for WEEKLY rules.

- The table implies that BYWEEKNO can be used with SECONDLY/MINUTELY/HOURLY/DAILY/WEEKLY and the result is to limit, but the spec says about BYWEEKNO "This rule part is only valid for YEARLY rules.".   I suggest either we loosen the restriction on BYWEEKNO to permit it's use with SECONDLY/MINUTELY/HOURLY/DAILY/WEEKLY or else we correct the table.  For consistency with BYMONTHDAY, I suggest we loosen the spec, but dissallow with MONTHLY rules, as I think you either have a month based view of life or a week based view of life, and the restriction reduces complexity and ambiguity.  I suggest:

      The BYWEEKNO rule part specifies a COMMA character (US-ASCII
      decimal 44) separated list of ordinals specifying weeks of the
      year.  Valid values are 1 to 53 or -53 to -1.  This corresponds to
      weeks according to week numbering as defined in [ISO.8601.1988].
      A week is defined as a seven day period, starting on the day of
      the week defined to be the week start (see WKST).  Week number one
      of the calendar year is the first week which contains at least
-      four (4) days in that calendar year.  This rule part is only valid
-      for YEARLY rules.  For example, 3 represents the third week of the
+      four (4) days in that calendar year.  This rule part is not valid
+      for MONTHLY rules.  For example, 3 represents the third week of the
      year.

- Note 2 and 3 say that BYDAY with BYMONTHDAY/BYYEARDAY is Limit, but in the case below the total result would be Expand:

FREQ=MONTHLY;BYDAY=MO;BYMONTHDAY=1,2,3,4,5,6,7,8,9,10,11,12,13,14

I can see that the BYMONTHDAY/BYYEARDAY are applied first and Expand, and then BYDAY goes on to Limit, whereas the BYDAY on it's own would Expand, but the notes make this a bit labourious.  I think what we are trying to say is that BYMONTH/BYWEEKNO/BYMONTHDAY/BYYEARDAY/BYDAY all create an expansion set, but when used together it is the union of all sets that is used.  I suggest we amalgamate the processing of them all, illustrate this in the table and add this text:

      If multiple BYxxx rule parts are specified, then after evaluating
      the specified FREQ and INTERVAL rule parts, the BYxxx rule parts
      are applied to the current set of evaluated occurrences in the
      following order: BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY,
      BYHOUR, BYMINUTE, BYSECOND and BYSETPOS; then COUNT and UNTIL are
      evaluated.

+      A particular BYxxx rule part may expand or limit the set of date/times 
+      generated by the rule. The expand or limit behaviour is governed by the 
+      FREQ value used for the rule.
+
+   Example:  
+        RRULE:FREQ=MONTHLY;BYMONTH=1,3,5;BYDAY=MO,TU
+
+      - The FREQ=MONTHLY value would match each of the twelve months 
+        in a year.
+      - The BYMONTH=1,3,5 rule part limits the matching months to just 
+        the 1st, 3rd and 5th in a year.
+      - The BYDAY=MO,TU rule part adds each Monday and Tuesday within 
+        the matching months to the recurrence set.
+
+      The table below shows the dependency of BYxxx rule part expand or limit 
+      behaviour on the FREQ value in the rule. When evaluating a rule, each BYxxx 
+      rule part must be evaluated in the order it appears in the table (i.e. 
+      BYMONTH evaluated before BYWEEKNO), irrespective of the expand or limit 
+      behaviour.
+
+      +----------------------------------------------------------------------------+
+      |            |SECONDLY|MINUTELY| HOURLY | DAILY  | WEEKLY | MONTHLY | YEARLY |
+      |------------+--------+--------+--------+--------+--------+---------+--------|
+      |BYMONTH     | Limit  | Limit  | Limit  | Limit  | Limit  | Limit   |        |
+      |------------+--------+--------+--------+--------+--------+---------+        |
+      |BYWEEKNO    | Limit  | Limit  | Limit  | Limit  | Limit  | N/A     |        |
+      |------------+--------+--------+--------+--------+--------+---------+        |
+      |BYYEARDAY   | Limit  | Limit  | Limit  | Limit  | N/A    | N/A     | Expand |
+      |------------+--------+--------+--------+--------+--------+---------+        |
+      |BYMONTHDAY  | Limit  | Limit  | Limit  | Limit  | N/A    |         |        |
+      |------------+--------+--------+--------+--------+--------+ Expand  +        |
+      |BYDAY       | Limit  | Limit  | Limit  | Limit  | Expand |         |        |
+      |------------+--------+--------+--------+--------+--------+---------+--------|
+      |BYHOUR      | Limit  | Limit  | Limit  | Expand | Expand | Expand  | Expand |
+      |------------+--------+--------+--------+--------+--------+---------+--------|
+      |BYMINUTE    | Limit  | Limit  | Expand | Expand | Expand | Expand  | Expand |
+      |------------+--------+--------+--------+--------+--------+---------+--------|
+      |BYSECOND    | Limit  | Expand | Expand | Expand | Expand | Expand  | Expand |
+      |------------+--------+--------+--------+--------+--------+---------+--------|
+      |BYSETPOS    | Limit  | Limit  | Limit  | Limit  | Limit  | Limit   | Limit  |
+      |------------+--------+--------+--------+--------+--------+---------+--------|
+
+      In YEARLY rules, BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY and BYDAY work 
+      together to expand the recurrence set.  Each on their own will specify
+      a range of valid instances, and when used in combination it is the union
+      of all ranges that create the required recurrence set.  So for example
+      in a YEARLY rule BYDAY=MO will mean every Monday, and BYMONTHDAY=1 will 
+      mean the first of every month, so when used together they mean the first of 
+      every month, but only when it's a Monday.  It would not mean on the first 
+      of every month and also on every Monday.  Likewise in MONTHLY rules, 
+      BYMONTHDAY and BYDAY work together to expand the recurrence set.

I think the above also explains the whole "special expand for weekly/monthly/yearly" concept which was another concept to understand and get wrong.

Nigel