Progress Events normative text

http://dev.w3.org/2006/webapi/progress/Progress.html

The draft says:

# The terms must, should, may, must not, should not, are used in this 
# document in accordance with [RFC2119]. A conformant implementation of 
# this specification meets all relevant requirements identified by the use 
# of these terms.

However, I think the terms are used a bit loosely so far. I will attempt 
to point out cases of this in the spec in this e-mail.


First, later in that section:

# User agent
# A user agent must implement all the requirements described for user 
# agents throughout this specification in order to be a conforming user 
# agent. A conforming user agent should implement all the recommendations 
# for user agents as well.

Given the definition of "must" and "should", this seems redundant. I would 
rather that the definition be given in the same style as the earlier 
definition of "Specification", as a definition rather than as a 
requirement.


# Content
# Conforming content must generate and consume progress events in
# accordance with the definitions of those events in this
# specification, and in accordance with any additional conformance
# requirements defined by a specification which describes an operation
# that can lead to progress events being dispatched.

I think it is wrong to make content non-conforming because it fires events 
in a fashion that isn't consistent with this draft. There are many reasons 
for doing so, e.g. to work around bugs in browsers, for testing purposes, 
as a quick way of patching around limitations in libraries, and so on.


# 2.1 Event definitions

The table comes before the concepts are introduced, which is confusing, 
because there are "must" requirements in the table that don't really make 
sense without context. For example, what does it mean for an event to be 
dispatched first? First relative to what?

However, in general I'm not sure that it makes sense for that table to 
have these requirements anyway. "load", for example, fires in many more 
cases than the table suggests, and sometimes, indeed in the most common 
cases in HTML, "load" and "error" are not alternatives but are unrelated.

Do these requirements mean that if a script calls dispatchEvent(), that 
the UA would be non-conforming if it dispatched the event? e.g. if the 
script fires 'abort', then 'load', then 'progress', then 'loadstart' 
twice, is the UA non-conforming? The text is unclear.

I think it would be helpful to consider how to test this section without 
another spec. I think one would find it impossible to do so. Thus, and 
since another spec would define the order with MUST-level requirements 
anyway, it seems like these requirements are effectively meaningless.

(As an editorial comment, I would personally recommend removing the table 
and instead having a flowchart show the recommended way for specifications 
to fire these events, instead of having a table with requirements.)


Below the table, there are some paragraphs that again may not make sense:

# User agents must implement these events such that by default the events 
# do not bubble, and are not be cancelable.

What does it mean for an event to not bubble by default? Or not be 
cancelable by default? Events don't have defaults.


# User agents must ensure that these events trigger event listeners 
# attached on Element nodes for the relevant event and on the capture and 
# target phases.

Isn't this redundant with DOM2 Events?


# No default action is defined for these events.

Doesn't this depend on the context? In particular, for HTML5's Offline 
Application Cache feature, the events _do_ have default actions, and thus 
_are_ cancelable.


# These events are in "no namespace", that is for the purposes of
# namespaced systems they use the null namespace.

Doesn't this depend on how they are instantiated? I don't understand what 
this sentence really means.


# Two kinds of initialisation methods are provided: one
# (initProgressEventNS) in which the namespace is required and must be
# null (any event in another namespace is not defined by this
# specification), and one (initProgressEvent) which assigns the null
# namespace automatically.

I don't understand what it means for the argument to be required to be
null. Why shouldn't people use the ProgressEvent interface with custom
events in their own namespace?


# This specification does not recommend use of one method over the
# other, and authors may choose whichever method suits them better for
# any given usage.

This "may" seems somewhat gratuitous, given that authors are really free 
to decide whatever they want to write in general anyway, and don't need a 
spec to allow them to make decisions like this. :-)


# 2.2 Event firing order

These problems continue in this section:

# The user agent must dispatch a loadstart event when a relevant operation 
# has begun.

What is a "relevant operation"?

Where must the event be dispatched?

How does this interact with equivalent requirements in other 
specifications? Does this mean that two events should be fired, one for 
the requirement in HTML5, say, and one for this spec?


# The user agent may dispatch one or more progress events while a network 
# operation is taking place.

On what EventTarget? Does this mean any network operation?

(These problems apply to the rest of the section too.)

# In short, there must be at least one loadstart event, followed by zero 
# or more progress events, followed by one event which may be any of 
# error, abort or load, according to the outcome of the operation, and 
# finally a loadend event must be fired.

This seems to be just a repetition of the previous requirements, so it is 
odd to use RFC2119 terminology again here. I recommend making one 
iteration normative and the other clearly non-normative to avoid any 
contradictions from vagueness in the less specific part from leading to 
implementation confusion.


# 2.3 Interface definitions

This is the one section that really needs normative text, since it is the 
one section that is really defining new features. However, as far as I can 
tell, it really doesn't define anything normatively. For example, the 
attributes have no UA requirements. Is lengthComputable supposed to throw, 
return true, return false, have any side-effects? Same for the others.


# initProgressEvent

With one exception, all the requirements in this section are redundant 
with requirements in WebIDL. For example, how to handle negative numbers 
passed to an unsigned long argument is a WebIDL concern and shouldn't be 
mentioned here. In general though, this method definition has almost no 
requirements on the user agent. It doesn't say that calling the method 
with a "true" argument in canBubbleArg mean that .bubbles is to be set to 
true, for instance.

(Personally I don't bother going into much detail for progress events; I 
just say "The initABCEvent() and initABCEventNS() methods must initialize 
the event in a manner analogous to the similarly-named methods in the DOM3 
Events interfaces. [DOM3EVENTS]".)

The only requirement that _is_ given and isn't redundant with WebIDL is:

# If any other parameter is passed, and lengthComputable is false, the 
# user agent must override this and set the value to zero.

This would mark the first time an initEvent method prevented a script from 
initialising an event to an arbitrary value. I think that's a bad 
precedent to set. Could you elaborate on why we want this requirment?


# Referring to progress events from other specifications

I think it would be helpful to define a set of terms such as "fire a 
progress event" that take as "arguments" (for lack of a better term) the 
event to fire, the event target, and the various other fields that are 
needed. For instance, we could have:

   *Fire a 'loadstart' event* without a default action means that the
   user agent must create an event named 'loadstart', with no
   namespace, which does not bubble, is not cancelable, which uses the
   ProgressEvent interface, with its lengthComputable attribute set to
   false, its loaded attribute set to 0, and its total attribute set
   to 0, and dispatch it at the given EventTarget.

   *Fire a 'loadstart' event with a default action* means that the
   user agent must create an event named 'loadstart', with no
   namespace, which does not bubble, is cancelable, which uses the
   ProgressEvent interface, with its lengthComputable attribute set to
   false, its loaded attribute set to 0, and its total attribute set
   to 0, and dispatch it at the given EventTarget. If the event is not
   canceled, then the user agent must execute the default action
   immediately after the event has been processed.

   *Fire a 'progress' event* with a progress amount and a total amount
   means that the user agent must create an event named 'progress',
   with no namespace, which does not bubble, is not cancelable, which
   uses the ProgressEvent interface, with its lengthComputable
   attribute set to true if the total amount is known and false
   otherwise, with its loaded attribute set to the progress amount,
   with its total attribute set to the total amount if the total
   amount is known and 0 otherwise, and dispatch it at the given
   EventTarget.

...and so on. Then, specs could just say:

   The user agent must then *fire a 'loadstart' event*. [PROGRESS]

...and:

   The user agent must then *fire a 'progress' event* with the
   progress amount /s/ and no known total amount. [PROGRESS]

...instead of the current situation where it's unclear who has to do what. 
This would also allow you to take the current conformance criteria, which 
are somewhat confusing and arguably meaningless (as noted above), and make 
the progress spec have clear testable criteria when used in conjunction 
with other specs.

You may also wish to consider how these requirements should integrate with 
the event queue mechanism now defined in HTML5. Maybe we should have terms 
like the above defined for queuing of events as well as straight firing of 
events. This would make referring to these events a lot easier, since in 
almost all cases these events will be queued instead of being synchronous.


# 4. Using progress events in Web content

These examples say "This example is informative and does not necessarily 
illustrate best practice". I think it is critical that we make sure that 
these examples illustrate best practice because frankly these are the 
examples that will be copied. They represent the best we'll ever see. We 
have to make them be the best we want to see.

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

Received on Friday, 31 October 2008 19:24:50 UTC