Re: Progress events progress...

On Fri, 22 Feb 2008, Charles McCathieNevile wrote:
> 
> http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.20 
> is a new Editor's draft, which should be ready to publish as a Working 
> Draft, and hopefully not generate any comments so we can take it to last 
> call about a month after that :)

I'm all in favour of publishing.


I don't understand the conformance in this spec. When a spec has two 
classess -- UAs and authors -- it's usually easy to tell which requirement 
applies to which. But when you add specs to the mix, I don't know how to 
tell which requirement applies to what.

In particular, this, combined with the apparent lack of requirements on 
some things but presence of requirements on others, leads me to have great 
difficulty interpreting the actual requirements in the spec.

For example:

| Must be dispatched first

Must be dispatched first in terms of what? By whom? I don't understand how 
to test this.

| By default these events do not bubble, and are not be cancelable.

How so? By default to what? Surely there is no default, the events bubble 
and are cancellable exclusively as set in their initProgressEvent() call.

| Two kinds of initialisation methods are provided: one in which the 
| namespace is required (and must be null)

Surely this is conflating the event types you are defining with the event 
interface you are defining. What is that requirement on? How do you test 
it? Does it only apply when init'ing one of the defined events? If so, 
it's redundant -- if the event was init'ed with a different namespace, it 
wouldn't be one of the defined events, and thus the requirement wouldn't 
apply.

| Specifies the expected total number of bytes of the content transferred 
| in the operation. Where the size of the transfer is for some reason 
| unknown, the value of this attribute must be zero.

The first sentence here has no requirement, it just defines the 
attribute's meaning. The second sentence, though, defines a requirement. 
Who is the requirement on? Why is the requirement to have a zero value a 
"must" when there is no requirement that the attribute have any other 
value? What if someone wants to use this interface with different 
conventions, such as making an unknown total Number.MAX_VALUE?

| This parameter overrides the intrinsic bubbling behavior of the event 
| and determines whether the event created will bubble

This definition seems to imply that the earlier comment regarding defaults 
has some sort of normative value, but I don't understand what -- is it 
saying that a ProgressEvent object, when created, has default values for 
its 'bubbles' attribute? Shouldn't this be left consistent with DOM 
Events? I don't know of any other event class that does this.


Incidentally, I _really_ don't understand the definition of the User Agent 
conformance class:

| A conforming user agent implements all the requirements described for 
| user agents throughout this specification. A conforming user agent 
| should implement all the recommendations for user agents as well.

First, why is there a conformance requirement in the definition of the 
conformance class to which it applies? Second, aren't those two sentences 
contradictory?

Similarly, the section starts with a paragraph saying:

| A conformant implementation of this specification meets all relevant 
| requirements identified by the use of these terms.

...but then says about the implementations in the spec conformance class:

| A conformant specification is one which includes all the requirements 
| identified in the section "Referring to progress events from other 
| specifications".

...which seems to contrdict it. I don't understand what is intended.


Frankly, as the editor of a spec that tries to use this spec, I'm not sure 
what would be best. I'm thinking that one option would be to change the 
focus of the Progress Events spec to be more of a guide, with the 
normative parts being only the definition of the IDL, with its methods 
defined in line with the DOM Events spec and the DOM Bindings spec, and 
with everything else just left up to the specs using it. The spec would 
then give a guide as to what event names are expected , in what order, but 
without making this normative. (I've already had to deviate from what this 
spec requires, mostly due to having more events to fire.)

To make this slightly more useful, maybe some "macros" could be defined, 
similar to the "fire a simple event" macro I have in HTML5, but like "fire 
a progress event" which takes "arguments" like the event name, the 
progress, the total, and the target element, with the "macro" setting up 
the bubbling and canceling behaviour, etc, and "returning" whether or not 
the event's default action should fire.

I don't know if it makes sense to have authoring conformance requirements 
for this spec at all.

Anyway. HTH,
-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'

Received on Friday, 22 February 2008 20:32:00 UTC