Hi Ian,
On Fri, 31 Oct 2008 15:24:14 -0400, Ian Hickson <[EMAIL PROTECTED]> 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
