Subject: CAP: nits

From: John Stracke <[email-masked]>
Date: Thu, 16 Aug 2001 14:36:51 -0400

Some nits from the CAP draft (typos, English problems, etc.):

    * Section 1.3 (the definitions):
          * "Calendar Properties" is defined as "An attribute of a
            calendar". Singular/plural mismatch.
          * "Calendar User Agent" is defined as "the client application
            that a CU or UG utilizes...". Should we strike "or UG"? A
            user group does not use a CUA; only a user does. This looks
            like a global-replace mistake.
          * "Calendaring and Scheduling System": "...services for
            accessing manipulating calendars...". Should there be an
            "and" after "accessing"?
          * "Heirarchical Calendars":
                * "A CS feature where a calendar have"--should be "has".
                * There's a definition of sibling relationships; I think
                  that should be omitted, since it's implicit in the
                  parent/child relationship.
          * "User Principal Name": the sentence "A CU's UPN to email
            address mapping..." is utterly unclear to me. What does it mean?
    * Section 2.1.1:
          * "One example of a site site policy"--strike one "site".
          * "calendar.site.com"--all example domain names in any RFC
            should be in "example.{com,net,org}", which are reserved for
            such purpose, so that, e.g., site.com doesn't get hit over
            and over by people reading the RFC.
    * Section 2.4.3:
          * "The Three Stooges. There is"--should be "are".
          * "The National Football League"--maybe find an example which
            will be better recognized outside the US?
    * 2.4.4:
          * "individual VCARs MUST be specifically granted to an
            authenticated CU". I think this is poorly phrased; as
            written, it sounds as if a CS MUST NOT forbid a CU from
            doing whatever they please. I think this phrase can just be
            struck, actually; its intent is redundant with with first
            part of the sentence ("All rights MUST be denied unless
            specifically granted").
    * 2.4.6: the examples are the same as in 2.4.3. Do they need to be
      repeated here?
    * 2.6: the port number, 5229, is in an awkward range. Something
      under 1024 would probably be better. (This came up in the London
      meeting.)
    * 2.7: the paragraph saying "The iCalendar METHOD property format
      has been updated with new values" should probably be moved up, so
      that it comes before the paragraph that lists some of these new
      values.
    * 2.8: The second-to-last sentence ("Followed by a DELETE...") is
      not a complete sentence.
    * 5.1.1: the ABNF for "search" does not include CRLF separators
      between "expand", "maxresults", etc.
    * 6.: as in 2.4.4, the first clause of the second paragraph seems to
      imply that a CU MUST be granted all rights. Again, I think this
      first clause can be struck.
    * 6.1: the "By implication" is not implied at all. "Subcalendars
      inherit from root" does not imply "subcalendars inherit from
      parents", although the other way around is true.
    * 6.2: "This setting overrides access While access control..."--this
      doesn't make sense; I think there's a cut-and-paste error here.
    * 7.1.4 and 7.1.5: MAXEXPANDLIST, MAXCALIDEXPAND, and
      MAXCALIDEXPANDLIST all seem to be used interchangeably; should
      they all be MAXCALIDEXPANDLIST?
    * 7.1.4: example #2 lists the same calid twice in the response.
    * 7.1.5:
          * AUTH: "Implementations MUST implement at least"--and then
            cuts off.
          * MAXICALOBJECTSIZE: "specifies The largest ICAL object"--I
            believe it should be "specifies the size of the largest...";
            an integer does not specify an iCalendar object.
    * 7.1.7 refers to "stuck in TCP-WAIT state". I believe that should
      be "stuck in TCP's TIME_WAIT state".
    * 7.1.11:
          * does not specify the syntax in which the members of the UPN
            are returned (examples don't count).
          * The group expansions seem to show that groups include
            themselves. Is this true? If so, why?
    * 7.2.1.2's restriction table:
          * Under "VCAP": "can send up PIPELINE"--should be "up to
            PIPELINE".
          * Under "VCAP", then "VCOMMAND": says "MUST at least one
            container"--a verb, Senator, we need a verb!
    * 7.2.1.7: the first example has a blank line after the
      "BEGIN:VEVENT". (There's no S:, so it's not a blank line from the
      server; it looks like it's just a typo.)
    * 7.2.2.1 is just riddled with spelling mistakes:
          * "automaticly" should be "automatically" (appears at least
            twice, and once in 7.2.2.7).
          * Apostrophes have been left out all over the place.
          * "...is not booked in your calendar, It is..."--change to
            "...calendar; it is...".
          * "The the CUA and CU could delete"--strike the second "the".
          * "...METHOD:DELETE the component an inform..."--"and".
    * 7.2.2.2: "If the CU wishes to keep the published entry."--sentence
      fragment.
    * 7.2.2.3: "This as described in [iTIP] and would be modified just
      like PUBLISH above". Don't say "just like"; that's too imprecise
      for a spec. Define what's going on; don't leave it up to the
      reader to intuit. Also, there should be an "is" after "This".
    * 7.2.2.7:
          * "may effect"--should be "affect".
    * 8:
          * 2.0.1: ">CRLF>.>CRLF>"--should that be "<CRLF>.<CRLF>"?
          * Several descriptions of response codes say "If can"--I think
            that should be "It can".
          * 8.3: "DATETIME value was too large"--all DATETIMEs are about
            the same size (15 or 16 bytes). Should that be "too far in
            future"?
    * 10.1:
          * Many of these property descriptions have spurious uppercase
            letters at the start of the second line.
          * CALMASTER: why does it have to be a mailto: URI? Why not im:
            (when IMPP is standardized), or http: (to get a page to read
            before sending a message)? If it does have to be email, why
            not a bare email address rather than a URI?
          * CSID: "hostname or virtual host name"--I haven't been able
            to find anything in the spec about virtual hosts. Did I miss it?
          * DEFAULT_VCARS: add a period after "CARID".
          * CURRENT_DATETIME:
                * What is this for? So the CUA can synchronize its clock
                  with the CS? If so, then doing it over TCP is probably
                  a bad idea. NTP already provides this functionality;
                  CAP shouldn't attempt to duplicate it.
                * It says it's a DATE-TIME value, but it's returned as a
                  local time and TZID. How? The DATE-TIME syntax doesn't
                  have room for a TZID.
    * 10.2:
          * DEFAULT_VCAR: refers to DEFAULT_VCAR in the calendar store;
            but there is no such property. There is a DEFAULT_VCARS
            property, though. Which should it be?
          * PARENT: "this calendars Parent" should be "this calendar's
            parent".
          * RELCALID: "A unique name for the calendar"--should that be
            "unique ID"?

-- 
/=================================================================\
|John Stracke    | http://www.ecal.com |My opinions are my own.   |
|Chief Scientist |================================================|
|eCal Corp.      |"Where's your sense of adventure?" "Hiding under|
[email-masked] <mailto:[email-masked]>|the bed."                                       |
\=================================================================/