Re: DOM3EV: Editorial comments

Hi Bjoern.

Bjoern Hoehrmann:
> Thanks for your comments. I've made a number of changes in response to
> them as detailed below.

Thanks for your prompt response!

> Please let us know if you have further input on the document and
> whether these changes are satisfactory. Thanks.

Unless I respond to the changes (or lack thereof) below, consider them
satisfactory.

> >  While this specification does not specify a full ordering [...]
> >
> >/full ordering/total ordering for event triggering/
> 
> I have not made this change. Could you elaborate on why you think the
> current text is not optimal and what you would like to see improved?

I thought that "total ordering" was the proper term.  I agree that "full
ordering" is unlikely to be misinterpreted.

> >* 1.4 Activation requests and behavior
> >
> >  Implementations dispatch the DOMActivate event as default action of a
> >  click event. This click event is either part of the activation request
> >  (e.g., a user requests activiation using a mouse), or synthesized by
> >  the implementation to accomodate legacy applications.
> >
> >I don't understand why synthesised DOMActivate events are always to
> >"accommodate legacy applications".  Is this because they assume that
> >activation always is because of a click event?
> 
> The subject of the sentence is the click event, while the text has many
> known shortcomings, I don't think it invites for this confusion.

Sorry, I did mean to say that I don't understand why synthesised click
events are always to "accommodate legacy applications".  I still don't
understand this.

> >s/respective/the relevant/
> 
> "the respective"?

I think that "respective" is used to single out items from some set of
items being talked about, so I think "relevant" is more appropriate
here.  But, whatever.

> TODO: the draft makes ambiguous use of the term "contextual information"
> but I'm not yet sure how to address that.

Generic and event-specific contextual information?

> >  An object which implements the Event interface is passed as the
> >  parameter to an EventListener.
> >
> >It's passed as the parameter to the handleEvent method on an
> >EventListener.  This sentence also doesn't say what happens for event
> >listeners that weren't added via addEventListener(NS) (such as on*
> >attributes).
> 
> I think this text is fine, could you elaborate on how you think this
> should be changed? It should not refer to handleEvent since there might
> not be such a method on some implementations of the interface (think
> ECMAScript Function objects). I don't think this is the right place to
> discuss on* attributes or similar features.

If an implementation of the interface does not have the handleEvent
method, then I don't think it's an implementation of that interface.  If
on* attributes and ES Function objects are mapped to EventListener
objects behind the scenes (even just conceptually) then it would be OK
just to refer to the EventListener interface here.

> >  The namespace URI associated with this event at creation time, or null
> >  if it is unspecified.  For events initialized with a DOM Level 2
> >  Events method, such as Event.initEvent(), this is always null.
> >
> >namespaceURI won't always be null if the event is initialised with
> >initEvent and then later with initEventNS with a non-null namespace URI.
> >Also, there will never be a namespace URI at creation time, only after
> >one of the init*EventNS methods is called.  Perhaps:
> >
> >  The namespace URI associated with the event at the time of
> >  initialization.  For events initialized with a DOM Level 2 Events
> >  method, such as Event.initEvent(), the namespaceURI will be null.
> >
> >.
> 
> "The namespace URI associated with this event at initialization time,
> or null if it is unspecified. DOM Level 2 Events initialization methods,
> such as Event.initEvent(), set the value to null."?

That sounds OK to me.

> That is incorrect, initEvent sets the namespaceURI to null just like
> initEventNS would when namespaceURI is null or the empty string. I do
> not think this should be changed for the reasons you cite, even a minor
> change like s/same behavior/same general behavior/ would invite readers
> to investigate which subtle differences there might be, while there are
> just incredibly obvious differences.

Ah yes, of course it does.  Another example would be better, then, such
as the description of initMouseEventNS saying that it has the same
behaviour as initUIEventNS.  So it's these "incredibly obvious
differences" I was worried about, since it says the behaviour of the
methods are all the same.  It's clear to me that it's meaning to say
that the first paragraph of the description of Event.initEvent applies
to all of these various methods; I just thought maybe this could be made
clearer somehow.

> >* * Interface EventListener
> >
> >  The EventListener interface is the primary way for handling events.
> >
> >s/for handling/to handle/
> 
> Why?

A "way for" something doesn't sound right to me, whereas "way to" or
"method for" do.  Not sure if there's some underlying grammatical reason
for this.

> >The parameter name should be changed from "eventType" to
> >"eventInterfaceName" or something similar, to indicate more accurately
> >its purpose.
> 
> This is an identifier that identifies the interface, your name suggests
> that it is the name of the interface which it is not. I don't know of a
> better name, if you can find one...

That's a bit of a subtle difference, isn't it?  Especially when the
identifier that identifies the interface happens to be equal to the
interface name (except in the case of the legacy "MutationEvents",
etc.).

> >  This event should logically happen before the event keyup is produced.
> >  [...]
> >  This event should logically happen after the event keydown is
> >  produced.
> >
> >s/logically happen/be dispatched/g, if that is what it means.
> 
> Implementations generate and dispatch event objects because the event
> that corresponds to the object occured or happened; I think this is fine
> as is.

Ah, another subtle distinction I hadn't considered.  In this case,
though, the text shouldn't say that the keyup event is "produced"--I'd
say that event objects are produced (or created) and then dispatched,
but events happen.

-- 
 Cameron McCormack			ICQ: 26955922
 cam (at) mcc.id.au			MSN: cam (at) mcc.id.au
 http://mcc.id.au/			JBR: heycam (at) jabber.org

Received on Wednesday, 19 April 2006 23:57:40 UTC