Re: Progress Events normative text

Hi Ian,

On Fri, 31 Oct 2008 15:24:14 -0400, Ian Hickson <ian@hixie.ch> wrote:

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

I guess  
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.25  
in particular, since that was the latest draft when I received this email.

> The draft says:
>
> # The terms must, should, may, must not, should not, are used in this
> # document in accordance with [RFC2119]...
>
> 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.
...
> # 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.

Having received several comments asking for real clarity on what is  
required (including from you), I am happy to stick with redundant  
statements, where they serve to repeat a requirement and don't cause  
confusion.

> # 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.

These are conformance requirements. Nothing forces content to be  
conforming, but it is valuable to have a clear explanation of what  
conformance means (otherwise why would you have bothered commenting on the  
need for such clarity).

> There are many reasons for doing so...

There are some reasons why this might be done, but I don't see any example  
sufficiently compelling to effectively abrogate a sense of conformance for  
content.

> # 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.

On the other hand, introducing the concepts before the table breaks the  
principle of "pyramid writing".

Having a simple summary of a longer section be the first part of that  
section can aid overall comprehension of that section. Conversely,  
presenting the reader with a lot of prose that must be waded through can  
actually pose a significant barrier to efficient understanding of the  
content.

The table does not stand on its own until the rest of the content is  
known, but it provides a shorthand that can be used to understand the  
whole section - and so for a repeat reader I believe it is a helpful  
shorthand (so long as it does not contradict what follows, or provide a  
misleading impression by omission of important data). Likewise for an  
initial reader it gives them a conceptual framework they can then adorn  
with the further information supplied afterwards, rather than requiring  
them to digest a lot of data before they have such a conceptual framework  
for processing it.

> For example, what does it mean for an event to be
> dispatched first? First relative to what?

First relative to other events defined by this specification. Do you find  
that assumption unnatural? If so, what did you think it referred to?

(It is possible to misunderstand anything, with a small effort. My goal in  
this spec is to make it *sufficiently clear*, so it is possible to  
understand it correctly with less effort than it takes to imagine an  
alternative meaning. Adding more prose to the specification /ipso facto/  
makes misunderstanding more likely, so there is a tension between  
comprehensiveness and comprehensibility).

> 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.

I will look at clarifying the fact that statements are relative to things  
defined within the specification.

> 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.

If the script (content) calls for the events to be dispatched in a  
non-conforming order, then the content is non-conforming. That a  
conformant UA can support non-conformant content is unclear - I will  
clarify that in the text.

> 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.

This spec places certain requirements on other specs that use these  
events, in order to provide some ground level of interoperability in  
usage. However, it is by design impossible to test these events without  
some other specification - they are not intended to be useful in any  
stand-alone context but are designed to be integrated into multiple  
specifications.

> (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.)

If I find the time to draw up a flowchart, I will include it as well. Feel  
free to offer one if I haven't yet produced anything (or to offer an  
improvement if I do).

> 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 agent implementations of events have defaults - either the user agent  
(absent other considerations) makes the event bubble, or it doesn't.  
Typically based on some setting or assumed setting of the relevant DOM  
attribute.

This specification defines some default values for the events it defines,  
as others have done before. In practical terms, such definitions mean that  
these events can be understood to have some 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?

See above re redundancy.

> # 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.

I will clarify that no defaults are defined *in this specification*. It  
appears to me that this means the text should be clarified, to allow  
specifications to make events bubble/cancelable and therefore require UAs  
to implement what the defining spec says.

> # 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.

No, it doesn't depend on how they are instantiated. If they are created  
with a non-namespaced method, or if they are created with a null  
namespace, then they are defined by this specification. If not, they are  
some other type of event. Perhaps a reference to the relevant part of the  
namespaces specification would help.

> # 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?

There is no prohibition on or recommendation against doing that. This  
specification simply refrains from any attempt to define what such events  
might mean.

> # 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. :-)

Redundancy again.

> # 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"?

One which dispatches progress events.

> Where must the event be dispatched?

On the object responsible for the operation.

> 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?

No. The event in HTML5 that is the event initially defined in this spec,  
with further specification relevant to HTML5-specific features (if I am  
not mistaken).

> # 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?

Any one that can fire progress events. (Technically it need not be a  
network operation actually, that is just the use case for which this spec  
has been designed and optimised).

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

Feel free to suggest something concrete.

> # 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.

It is a repetition. That is the common understanding of text introducing a  
summary, such as "in short".

> 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.

I prefer to ensure that the two texts are not contradictory. That way  
understanding either of them is sufficient for a correct implementation.

> # 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.

When the spec was originally written there was no WebIDL spec. I will  
review the two in parallel and make any appropriate changes before asking  
for last call.

> (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]".)

It refers (and normatively defers) to DOM3EVENTS as as you do. It simply  
provides a little more of the information there in a redundant manner.

> 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?

As a defined method for handling error states that doesn't force user  
agents and interlocking scripts to work out how to deal with any arbitrary  
values but only those which make sense.

If you want this changed, could you elaborate on why, and raise an issue  
in the Web-apps issue tracker?

> # 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]

However, this restricts specs in their ability to customise the use of  
such events. While the progress events spec is short, and the events are  
simple, any specification can include such a definition that includes  
specific customisations, and refers to the Progress Events spec (in much  
the way that the Progress Events spec provides a rough guide to creating  
the events as well as clarifying that they are based on DOM3EVENTS.

> ...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.

Specs can require/allow firing events, and use a simple reference to the  
progress events spec to define those events, or can clarify and in certain  
ways customise what that means in the context of the specific  
specification (for convenience of readers), merely referring to the  
Progress Events spec as a reference defining what progress events are.

> 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.

Yes, considering this would be valuable. Are there any plans to split this  
work out in order to provide some sense of stability in this decade, for  
the various non-HTML specifications that make use of Progress Events?

> # 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.

Whatever we make does not necessarily represent best practice. That is in  
part because the specification defines the events before a significant  
body of practice has been developed. If you expect these to be the best  
exampels we ever see then I think you are seriously underestimating the  
intelligence of everyone who will use this spec but has not been involved  
in its development.

That said, the examples should indeed be as good as we can make them. Feel  
free to propose further examples for inclusion.

Thanks for all the comments. I will be working on the draft over the  
weekend...

cheers

Chaals

-- 
Charles McCathieNevile  Opera Software, Standards Group
     je parle français -- hablo español -- jeg lærer norsk
http://my.opera.com/chaals       Try Opera: http://www.opera.com

Received on Friday, 21 November 2008 01:46:30 UTC