Subject: cap-10 sections 1-5 comments/questions (mostly boring)

From: Dan Winship <[email-masked]>
Date: 02 Apr 2003 09:38:11 -0500

Trying not to duplicate too much the comments made by the last
critiquer...

> 1. Introduction

> the CUA is responsible for correctly generating iCalendar objects to
> non CAP processes.

Not grammatical. s/to/for/ ?

> The definition of new components, properties, parameter's, and value
> types are broken into two parts.  The first part summarizes and
> defined the new objects.  The second part provides the detail and any
> ABNF for those objects.

s/'//
s/are/is/
s/defined/defines/
s/any// ? [Whoever wrote most of the text likes the word "any" a lot]

> 1.1 Formatting Conventions

A forward reference to 1.2 and 1.3 would help a lot here

The odd use of "quoted-string" instead of "quoted string" matches the
other calendaring RFCs, so I guess it's not considered a bug? Likewise
the random selection between the words "capitalized", "uppercase",
"upper-case", and "upper case" in different paragraphs?

> Enumerated values defined by this memo are referred to with
> capitalized text, either alone or followed by the word "value".

Should be "capitalized, quoted strings of text" like everything else.

> Calendar components defined by [iCAL] ...

should start a new paragraph. Also, it shouldn't say "defined by [iCAL]"
since the convention is used for calendar components defined by CAP as
well. Likewise, "Properties defined by this memo" and "Property
parameters defined by this memo" shouldn't say "defined by this memo".

> 1.3 Definitions

These need to be re-alphabetized before last call.

> BOOKED - ...

This isn't a definition of BOOKED, it's a definition of object states.
It's also completely incomprehensible. The stuff in section 2.2 is more
salvageable, so this definition should probably just go away / be merged
there.

> Calendar -  A collection of logically related objects or entities
>    each of which may be associated with a calendar date and possibly
>    time of day.  These entities can include calendar properties or
>    components.  In addition, a calendar might be related to other
>    calendars with the "RELATED-TO" property.  A calendar is
>    identified by its unique calendar identifier.  The [iCAL] defines
>    the initial calendar properties, calendar components and
>    properties that make up the contents of a calendar.

For such a large definition, this doesn't say much. The first two
sentences are incredibly vague. (Is my inbox a Calendar?). The
"RELATED-TO" sentence feels arbitrarily tacked-on. How about:

        Calendar - A collection of iCalendar components and properties
        associated with a particular CU, encapsulated in a "VAGENDA"
        component.

> Calendar Address -  Also See Calendar URL - they are one in the same
>    for CAP addresses.  The calendar address can also be the value to
>    the "ATTENDEE" and "ORGANIZER" properties as defined in [iCAL].

Likewise with the vagueness.

> Calendar Policy -  A CAP operational restriction on the access or
>    manipulation of a calendar.  These may be outside of the scope of
>    the CAP protocol. An example of an implementation or site policy
>    is, "events MUST BE scheduled in unit intervals of one hour". 

s/MUST BE/must be/, since this is not an RFC 2119 MUST. (There are lots
of other places where "MUST BE" should probably be "MUST be".)

If the example policy above is not considered pathological behavior on
the part of the CS, then there really ought to be a REQUEST-STATUS
meaning "command failed because it violates policy" (and/or "command
succeeded after mangling parameters to suit policy") so the CUA and CU
have some hint about what's going on. 

> Calendar Store (CS) -  The data and service model definition for a
>    Calendar Store as defined in this memo.

Kinda circular...

> Calendar Server -  An implementation of a Calendar Store (CS) that
>    manages one or more calendars.

Which is different from a Calendar Store how? "Calendar Server" doesn't
get used anywhere else in the spec anyway. How about something like:

        Calendar Store (CS) - A server that a CUA connects to to query
        and manipulate calendars. Also called a Calendar Server.

>  Calendar Store Identifier (CSID) -  The globally unique identifier
>    for an individual CS.  A CSID consists of the host and port
>    portions of a "Common Internet Scheme Syntax" part of a URL, as
>    defined by [URL].

The CAP spec mixes and matches references to [URL] and [URI]. The older
[URL] references need to be updated to point to [URI] instead.

> Calendar Store Components -  Components maintained in a CS specify a
>    grouping of calendar store-wide information.

Should be "Components maintained in a CS THAT specify"?

> Calendar Store Properties -  Properties maintained in a Calendar
>    Store calendar store-wide information.

Likewise "that specify calendar-store-wide information"?

> Delegate
> Designate

Neither of these definitions are used elsewhere in the document.

> Overlapped Booking

Likewise, this definition isn't referred to elsewhere, and the text
would probably be more understandable if it was moved to 8.37 ("TRANSP
Property")

> 2. Additions to iCalendar

The organization here seems arbitrary. (Why is "New Value Types" (2.1) a
parent to "New Parameters" (2.1.1)?).

> A CU may wish to set their own alarm (local alarms) on components.
> These local alarms are not to be forwarded to other CUs, CUAs, or CSs
> as are the "SEQUENCE" property and the "ENABLE" parameter.

I think that is supposed to mean that SEQUENCE and ENABLE should *not*
be forwarded, but I don't think it actually succeeds in meaning that.
The semantic discussion should probably just be xreffed from here
anyway.

> 2.1 New Value Types (summary)

should have hyphens between the names and definitions for consistency
with everything else

> CALQUERY The "CAL-QUERY" value type is ...

s/CALQUERY/CAL-QUERY/

> ID -  The "ID" parameter specifies a unique identifier to be used for
>    any outstanding commands.

That makes it sound like you specify it once and it keeps applying to
new commands later. "to be used to identify responses to a command".

> LOCAL -  The "LOCAL" parameter in CAP is used to tag a "SEQUENCE"
>    property in a "VALARM" component to signify that a VALARM is local
>    or to be distributed.  (Section 7.5).

"to signify whether or not a VALARM is to be distributed"

> SEQUENCE -  When the "SEQUENCE" parameter is used in a "VALARM"
>    component it uniquely identifies the instances of the "VALARM"
>    within a component.

s/within a component/within its parent component/? (for clarity)

> 2.1.2 New Properties (summary)

The style of definition here is different from the preceding section. In
2.1.1, most of the defs used the parameter name right away ("The
"OPTIONS" parameter blah blah blah"), whereas many of these specify it
near the end or not at all ("The CAP commands, as well as replies are
transmitted using the "CMD" property" [which needs a comma after
"replies" btw]). Also, some of the "definitions" are actually
rationales. Eg:

> ALLOW-CONFLICT -  Some entries in a calendar might not be valid if
>    other entries were allowed to overlap the same time span.
>    (Section 8.1)

which does not define ALLOW-CONFLICT. Likewise for ATT-COUNTER.

> CAP-VERSIN

typo

> CAR-LEVEL -  The level of calendar access level supported.

remove the second "level"

> DEFAULT-CHARSET - The list of charsets supported by the CS

Ugh. Probably too late to change this (and DEFAULT-LOCALE and
DEFAULT-TZID) to "SUPPORTED-CHARSETS" or something? (Especially since
"DEFAULT-VCARS" really does mean "default VCARs".)

> EXPAND -  This property tells the CS if the query reply should expand
>    components into multiple instances.  The default is FALSE.

None of the other properties mention a default. Does that belong here?

> MAXDATE -  The maximum date supported by the CS.  (Section 8.20)
> MINDATE -  The minimum date supported by the CS.  (Section 8.21)

MAXDATE and MINDATE are fine names for protocol elements, but the
English description would read better with "latest" and "earliest".

> RECUR-ACCEPTED -  If the implementation support recurrence rules.
> RECUR-EXPAND -  If the implementation support expanding recurrence

s/support/supports/ in both

> REQUEST-STATUS -  The [iCAL] "REQUEST-STATUS" property is extended to
>    include new error numbers.  (Section 8.28)

That should be in section 2 rather than 2.1.2 then, right? Likewise
TRANSP. Either that or 2.1.2 should be "New and Modified Properties"

> VAGENDA -  CAP allows the fetching and storing of the entire contents
>    of a calendar.  The "VCALENDAR" component is not sufficient to
>    encapsulate all of the needed data that describes a calendar.

The second sentence is wrong, right? VCALENDAR is used to encapsulate
complete CAP commands/replies, VAGENDA is used to encapsulate calendars
inside VCALENDARs.

> 2.2 Relationship of RFC-2446 (ITIP) and CAP

This section is really hard to understand, but I don't have any concrete
suggestions right now.

'marked for delete state' should be '"DELETED" state' everywhere for
consistency. ?

> 3.3.1 Use of BEEP, MIME, and iCalendar

> The [BEEP] data exchanged in CAP is a iCalendar MIME content that
> fully conforms to [iCAL] iCalendar format.

Fix "a iCalendar". I wasn't paying attention to the whole multipart
flame war, but did people agree that this is supposed to mean "The
Content-Type of [BEEP] data exchanged in CAP is always text/calendar"?
If so, it would be nice to be explicit about that.

> 4.2.1 Access Control and NOCONFLICT
>
> The "TRANSP" property can take on values "TRANSPARENT-NOCONFLICT" and
> "OPAQUE-NOCONFLICT" that prohibit other components from overlapping
> it.  This setting overrides access.

I don't think this section is necessary (or even correct). "Overrides
access" implies that if I don't have any access to a given calendar, and
I try to create an appointment in it that would overlap an NOCONFLICT
appointment, then I should get a 6.2 (overlap error) instead of a 6.4
(permissions error), because NOCONFLICT overrides access.

What I think it really is supposed to mean is "even if you have
permission to write to a calendar, you can't make an appointment that
overlaps a NOCONFLICT appointment". But that's not a permissions-related
thing, and it doesn't need to be explicitly stated any more than "even
if you have permission to write to a calendar you can't make an
appointment that ends before it starts".

(If you do keep this section, the final sentence in it refers to the
wrong error code. It says 6.3 but should say 6.2.)

> 4.2.2 Predefined VCARs

> CARID:REQUESTONLY -  Specifies the "GRANT" and "DENY" rules to UPNs
>    other than the owner of the calendar the ability to write new
>    objects with the property "METHOD" property set to the "REQUEST"

delete first "property"

> 4.2.3 Decreed VCARs

> To the CUA any "VCAR" component with the "DECREED" property set to
> "TRUE" can not be changed by the currently authenticated UPN, and
> depending on the implementation and other "VCAR" components; might not
> be able to be changed by any UPN using CAP, and never when the CUA
> gets a "DECREED:TRUE" VCAR.

s/;/,/
I think everything after the last comma is a remnant of a previous
wording and needs to be deleted.

> When a user attempts to modify or override a decreed "VCAR" component
> rules an error will be returned indicating that the user has

s/ rules/,/ (or maybe just s/rules/rule,/ ?)

> 4.3 CAP Session Identity

> A UPN with a non-null Username and null Realm, such as "bob@" could be
> a security risk and MUST NOT be used.

That's silly. It invents a security hole and then tells you not to use
it. It should just say that that's not a UPN. (And in fact, the ABNF for
"upn" doesn't allow that.)

> 5. CAP URL and Calendar Address

s/RFC 2396/[URI]/ throughout, and likewise fix "RFC 2718" refs