[Calendar API] editorial comments

http://www.w3.org/TR/2011/WD-calendar-api-20110419/


This is copied from [1]:

Sorry for the delay in providing feedback. I was transitioning for the past few months and didn't have any time to review the DAP work items. I'm now trying to focus on them as part of my new job. 

I can't tell if the document is en-GB or en-US. The API itself [at least for Contacts] is en-US.

* I didn't spend the time to identify en-US cases in general, but I'm confident they exist.
[en-GB]> how to add and update calendar events, utilising existing
[en-GB]> Its behaviour depends on the type of input:
[en-US]> ... or standardization.
[en-GB]>    iCalendar parsing and serialision;
[en-GB]>    hCalendar parsing and serialision;


Here are the en-US/en-GB terms:
* authorize/authorise
* behavior/behaviour
* favorite/favourite
* fulfill/fulfil
* minimize/minimise
* utilizing/utilising
* serialization/serialisation

** note that it's incredibly hard to write this section as my Email client helpfully corrects the British instances to American spelling for me :/.

Personally, I'd prefer en-US. Originally (for Contacts) I was going to suggest selecting en-GB, because I thought that was the dominant form, however, I think that en-US is dominant, so the items I've identified as [en-GB] should be changed.

Other editorial comments...
> A set of Security and Privacy Considerations are presented for the discretion of both implementors

s/implementors/implementers/g

> A conforming implementation of this specification must provide a mechanism that protects the user's privacy and this mechanism should ensure that no calendar information is creatable, retrivable,

s/retrivable/retrievable/

> A user agent must not create, retrieve, update or delete calendar information to Web sites without the express permission of the user.

*to* web sites? That happens constantly today, e.g. whenever I use Google Calendar.

This section almost needs an "in the context of this API" or something...

> The user interface must include the URI of the document origin, as defined in [HTML5].

I feel like I've commented on this stuff before, was it in the Contacts feedback [1]; could someone apply all of my editorial feedback from that specification to this one?

> Those permissions that are acquired through the user interface

s/Those p/P/

> and that are preserved beyond the current browsing session (i.e. beyond the time when the browsing context, as defined in [HTML5], is navigated to another URL) must be revocable and a user agent must respect revoked permissions.

Right, please see [1].

> Recipients are invited to dispose of calendar information once that task is completed,

s/invited/encouraged/ ?

> Care should be taken when retransmitting and use of encryption is encouraged.

"use of encryption" is unfortunate.... should we spell out that data should be encrypted and that its key should not be left adjacent?

>    Find calendar event items in the calendar based on an CalendarEventFilter object.

s/an/a/

> When called, it immediately returns, and then asynchronously start a find calendar event items process defined as follows:

s/start/starts/

>    This attribute can be specified as a positive valid date or time string.
>    , denoting a one-time reminder or as a negative value in milliseconds

Random stray comma here....

> denoting a relative relationship to the start time of the calendar event.

>    A relative reminder is recommended for setting a reminder for recurrent events.

I prefer recurring over recurrent (this comment probably applies elsewhere too):

s/recurrent/recurring/g ?

> This interface has known limitations for capturing recurrent events that
> will be addressed in a next revision of the document.

"a next" => "a following" | "a future" | "the next"

>   The possible values are:
>        [1..365] (number of days from the first day of the year)
>        [0..-364] (number of days before the last day of the year)

In leap years there are 366 days, I believe, so your bounds are wrong, they should be 366 and -365.

>    If this parameter is set to null the event item does not have any
> fixed expiry date and the event is scheduled to continue indefintely.

s/indefintely/indefinitely/

>    If this parameter is set to null the event item does not have
> any fixed interval and the event interal should be derived from the

s/interal/interval/


>    NOTE: This property only applies to yearly occurrences.

Do you mean "occurrences" or "recurrences"?

>    NOTE: This property only applies to monthly occurrences.

>    The possible values are:
>        [1..4] (number of weeks from the first week of the month)
>        [0..-3] (number of weeks before the last week of the month)

This is probably underspecified. If I select "2", does that mean "7 days from the first day of the month", or does it mean "7 days from the first {day-of-week-starter} of the month"? I'm going to assume that you want the former, and that you'll add text to provide for this.

All months except February in non leap years have 5 weeks (some have six if you use the alternate counting algorithm noted above)

This should be 1..5 and 0..-4 (or 1..6 and 0..-5).

>    A boolean value to indicate whether multiple Calendar objects
> are returnable 

I'm not a fan of "returnable", I'd prefer "can be returned", but..

> endAfter of type DOMString
> ... as a valid date or time string..
> endBefore of type DOMString
> ... as a valid date or time string..
> startAfter of type DOMString
> ... as a valid date or time string..
> startBefore of type DOMString
> ... as a valid date or time string..

Each of these things ends with *two* periods....

>    error CalendarError ✘ ✘
> The Calendar API related error object of an unsuccessful asynchronous operation.

s/of/for/ ? (/g?)

> The CalendarError interface encapsulates all errors in the manipulation
> of CalendarEvent objects in the Calendar API.

I'm not a fan of "in the manipulation of", perhaps "while manipulating" ?

>    An error code assigned by an implementation when an error has
> occurred in Calendar API processing.

s/occurred in Calendar API processing/while [handling|processing] a Calendar API/ ?

>    An invalid parameter was provided when the requested method was invoked.

WebIDL talks about "operations" instead of "methods", this spec is inconsistent, you might want to use "operations" in most cases when you're talking about WebIDL operations....
 
>    The requested method is not supported by the current implementation. 

If my UA supports something but one of its three backing stores does not, I don't want the person reading this API spec to believe that my UA is defective when it occasionally throws this. Not sure how to improve the wording.

>    Access to the requested method was denied at the implementation
> or by the user.

s/at the/by the/
s/implementation.*user/user or implementation/

> It might just be simpler to use pass RegExp objects around.

s/use pass/pass/

> The rules for processing filter combinations is defined below

s/is/are/

> and is

s/is/are/

>   Purpose:  To specify whether the event is an all day occurance.

s/occurance/occurrence/

> in order to acheive add and update functionality.

s/acheive/achieve/

> On invocation of a valid Calendar resource, the user agent should,
> on successful download of the valid Calendar resource,

s/on successful download of/upon successfully downloading/

>    If Calendar contains a UID key then process the valid
> Calendar resource as follows.

s/./:/ ?

> ... that matches exactly the value of the UID provided.

s/UID provided/provided UID/

> (i.e MatchedEvent is not-null)

s/i.e/i.e./

> The following example shows the process in which a web site

s/in/by/

> Use Case 1: A web application would like to access the device calendar
> A Web Application on behalf of the user would like to access the user’s
> device calendar so it can be presented to the user in the context of
> browsing a Web Application.
> For example, the user is in the process of completing an online flight
> reservation and would like to view the device calendar to check his/her
> schedule.

The use case should note that the web application does not want to drown under the load of 20 years of calendar events. (Most likely it only wants to see a month or a week.)

> would like to be reminded 5 minutes prior to the auction is closed

s/is closed/closing/

> so he may wish to change his bid price.

s/wish to//

> reminded one hour prior to the appointment that may allow him to 

s/that may/to/

>     must support CRUD operations on individual Calendar entries (e.g. create, add, delete, update);

What's CRUD? It isn't linked and Create/Add/Delete/Update would be CADU not CRUD.

>    must provide the ability to set a reminder on per Calendar entry basis.;

s/.//

[1] http://lists.w3.org/Archives/Public/public-device-apis/2011Jun/0081.html


---------------------------------------------------------------------
This transmission (including any attachments) may contain confidential information, privileged material (including material protected by the solicitor-client or other applicable privileges), or constitute non-public information. Any use of this information by anyone other than the intended recipient is prohibited. If you have received this transmission in error, please immediately reply to the sender and delete this information from your system. Use, dissemination, distribution, or reproduction of this transmission by unintended recipients is not authorized and may be unlawful.

Received on Tuesday, 28 June 2011 21:38:24 UTC