Re: I18N last call comments on DOM 3 Events

Hello Philippe,

Many thanks for your careful work. Some comments below.
I'm copying the I18N IG list because the comments are from the I18N WG.

I'm giving you my opinion here, and will ask the I18N WGs Core TF
for further input and approval at our next teleconference (tomorrow).

For reference, the issue tracking document is at
http://www.w3.org/2002/07/DOM-Level-3-Events-issues/issues.html.
This does not include purely editorial issues.


At 15:28 03/07/03 -0400, Philippe Le Hegaret wrote:
>Here is the response to the I18N last call comments on DOM3 Events.
>Please, let us know if you agree or not with them. Thank you for your
>complete and detailed review of the DOM Level 3 Events draft.
>
>Regards,
>Philippe
>
>
> > 1.2.1 Phase, 1st para: "target ancestor" is misleading, it took me
> > while to understand that it was "ancestor of the target" (or "target's
> > ancestor"), not some ancestor that is qualified as a target.  Same
> > comment for other instances of "target ancestor" later on.
>
>Fixed. (now using target's ancestor)

okay


> > 1.2.2.1, 1st para: this sentence is hard to understand at this point,
> > as one doesn't know yet what "type", "category" and "group" mean.
> > Looking at the glossary didn't help.
>
>We added pointers to the respective sections.

okay


> > 1.2.2.6, 1st para: "The effect could be:" Under what conditions?
> > Under control of the API?  At implementer's choice?
>
>clarified as follows:
>[[
>The effect can be:
>  * immediate: no more event listeners from the same group will be
>    triggered by the event object (see Event.stopImmediatePropagation());
>
>  * deferred until all event listeners from the same group have been
>    triggered on the current node, i.e. the event listeners of the same
>    group attached on other nodes will not be triggered (see
>    Event.stopPropagation()).
>]]

okay


> > 1.4, 1st para: "The event type is composed of a local name and a
> > namespace URI as defined in [XML Namespaces]."  It would be far better
> > to say "namespace name" instead of "namespace URI" and to point
> > normatively to Namespaces 1.1 (http://www.w3.org/TR/xml-names11/), now
> > in CR and therefore referenceable from a WD or CR.
> >
> > One reason is to allow IRIs, another is to buy in all the behaviour
> > defined in Namespaces, instead of paraphrasing it in the Note below
> > the 1st para.  This note, also, appears to contain normative language
> > that is made non-normative by being in a Note.  Only the last two
> > sentences need to survive, the rest should be farmed out to the
> > Namespaces spec.
>
>The language was taken from DOM Level 3 Core and, as said in the Note,
>no lexical check is done on the namespace URI. The new section 1.3.2
>"DOM URIs" (to be published soon, if not already) should clarify the
>relation between namespace URI, URI, and IRI. The reference to "XML
>Namespace" was removed in the text and the glossary now defines
>namespace URIs as follows:
>[[
>A namespace URI is a URI that identifies an XML namespace. This is
>called the namespace name in Namespaces in XML [XML Namespaces]. See
>also sections 1.3.2 " DOM URIs" and 1.3.3 " XML Namespaces" regarding
>URIs and namespace URIs handling and comparison in the DOM APIs.
>]]

I feel that in both cases (both Core and Events), it would be good
to explicitly mention IRIs to make sure developers don't miss that.
But I guess I could live with them being only mentioned in Core.
(as mentioned by Francois).


> > 1.4.2: There seems to be a contradiction between the listings for
> > "resize" and "scroll" in the table and the wording in 1.7.6 which
> > place them in the BasicEvents module, not UIEvent.
>
>The concept of "BasicEvents" was introduced in DOM Level 3, in order to
>expose the HTML events to XML user agents. Given that conformance and
>features are defined against the event types and not the DOM interfaces,
>it is not a contradiction. The name of a feature shouldn't have to do
>with the name of the interface.

okay


> > 1.4.3, 1st line: typo, "Were" -> "were".
>
>Fixed.

okay


> > 1.6, description of the "type" attribute of Event: the 1st sentence
> > says "must be an NCName", second sentence says "(colon) should not be
> > used".  This is redundant, except for the "should" and "must" which
> > are not consistent.
>
>We changed the two sentences to say:
>[[
>  The name should be an NCName as defined in [XML Namespaces] and is
>  case-sensitive.
>]]

okay


> > 1.6, description of the "initEvent" method of Event: there is a
> > mention of an "Event.localName" attribute which doesn't seem to appear
> > anywhere else.
>
>Fixed.
>
> > 1.6, description of the "initEventNS" method of Event: missing word
> > "before" between "multiple times" and "the event has been dispatched".
>
>Fixed.
>
> > 1.6, description of the "isCustom" method of Event: the description of
> > the return value is actually that of the isDefaultPrevented method.
>
>Fixed.
>
> > 1.6, description of the "stopPropagation" method of Event: "differed"
> > -> "deferred".  There are a couple of other instances of this one.
>
>Fixed.

all okay


> > 1.6.1, 1st para in description of the DocumentEvent interface: "It is
> > expected that the DocumentEvent interface will be implemented on the
> > same object..."  It would seem that interoperability would require a
> > MUST here.  Otherwise, how does one get to the DocumentEvent
> > interface?
>
>This section needs updates following the changes to the DOM Level 3
>Core. It should read:
>[[
>If the feature "Events" is supported by the Document object, the
>DocumentEvent interface must be implemented on the same object. If the
>feature "+Events" is supported by the Document object, an object that
>supports the DocumentEvent interface must be returned by invoking the
>method Node.getFeature("+Events", "3.0") on the Document object.
>]]

okay


> > 1.7.2, TextEvent interface: Yes!  And kudos for making the data
> > attribute be a DOMString, not a single character.
>
>You're welcome. Credits have to go to Martin Duerst and Nobuhisa
>Shiraishi as well for their help on the KeyboardEvent interface.

:-)


> > 1.7.2, issue paste-1: decision seems wrong.  An app that wants to be
> > alerted on text input (e.g. to implement something like an incremental
> > search) would miss important input.  And what if some voice-to-text
> > software uses the clipboard?
>
>We added the following sentence to the description of the textInput
>event:
>[[
>Where a "paste" operation generates a simple sequence of characters,
>i.e. a text without any structure or style information, this event type
>should be generated as well.
>]]

okay


> > 1.7.2, initTextEvent: since this interface is new to Level 3, this
> > method appears to be superfluous.  One can just call initTextEventNS
> > with a null namespace.  Same comment for KeyboardEvent and
> > MutationNameEvent.
>
>Having the non-NS methods is consistent with the rest of the API and,
>while it could be viewed as superfluous, it doesn't hurt the current
>design of the API to have them.

okay for me.


> > 1.7.2, description of initTextEvent: it gets really annoying to
> > re-read in each init*Event and each init*EventNS method that "This
> > method may only be called before the UIEvent has been dispatched via
> > the EventTarget.dispatchEvent method, though it may be called multiple
> > times during that phase if necessary. If called multiple times, the
> > final invocation takes precedence." Can't this this factored away
> > somewhere?  Also, the ones in TextEvent say "This method has no effect
> > if called after the event has been dispatched.", but not the others,
> > is there a reason?
>
>Fixed. Not sure if the new version is an improvement over the previous
>but at least, it is now consistent.

okay


> > 1.7.3, MouseEvent interface: thanks for the addition of altGraphKey,
> > but this is still missing an important modifier, that for the right
> > Ctrl key.  This is distinct from the left Ctrl key and is standardized
> > by ISO 9995 as the Group Select key.  It is a modifier just like
> > Shift, Alt, etc.  It is not the same as the Meta key, some keyboards
> > (notably Macintosh) have both.
> >
> > 1.7.4, KeyboardEvent interface: same comment as above for the missing
> > attribute for the right Ctrl modifier key.
>
>We don't support right or left in the modifiers. If an application
>wishes to distinguish right and left controls, it should listen to
>Keyboard events and get the location when the keyIdentifier is
>"Control".

Does the spec say so, or does the reader have to infer that?
The spec should say so.


> > 1.7.4, KeyboardEvent interface: it should be clarified in this section
> > that the pressing and releasing of modifiers keys are expected to
> > generate events, as the examples in Appendix A show.
>
>Added, in the appendix section on modifiers:
>[[
>Keys associated with modifiers generate, like other keys, "keydown" and
>"keyup" events [...].
>]]

okay


> > 1.7.4, description of "keyIdentifier", says "For a list of *possible*
> > values..." (emphasis mine).  This seems to be much too weak, there is
> > no conformance requirement at all and nothing for implementers of DOM
> > applications to rely on.  It is possible that a key will generate some
> > identifier as described in Appendix A, but it is also possible that it
> > will generate something else or whatever.  What is the poor programmer
> > to do?  This needs to be tightened, so that one can have a reasonable
> > expectation that the "Enter" key will generate "Enter", and so on.
>
>Reworded as follows:
>[[
>keyIdentifier holds the identifier of the key. The key identifiers are
>defined in Appendix A.2 "Key identifiers set". Implementations that are
>unable to identify a key must use the key identifier "Unidentified".
>]]

okay


> > Appendix A: this needs a thorough spell- and grammar-check.
>
>Fixed

okay


> > The index is mostly unusable in the printed (PDF) version, most
> > entries have no associated page numbers.
>
>Martin pointed out some of the problems in the PS and PDF
>versions. Well, I can't guarantee that we will be able to fix all of
>them unfortunately but we will do a reasonnable attempt.

thanks


> > 1.4 and other places: Use IRIs, not URIs (I think the DOM WG is
> > already looking into this issue)
>
>Correct, the Events module needs to be aligned to the Core one.

okay


> > 1.7.2 there should be a prominent pointer from here to the examples in
> > Appendix A.
>
>Fixed
>[[
>Refer to Key identifiers for keyboard events for examples on how text
>events are used in combination with keyboard events.
>]]

Can you change the text so that it explicitly mentions "Appendix A"
(at least in the printed version).


> > 1.7.4 DOM_KEY_LOCATION_UNKNOWN: It seems to be a bad idea to have this
> > at 0x04. Why not e.g. move it up to 0x80, so that there is space for
> > potential future standardization?
>
>This constant has been removed.

Does this mean that there are no private key locations? If so, that's
okay with us.


> > App. A: U+HHHHHH notation: This should use the standard form: At least
> >      4 and at most 6 hex digits, leading digits only for 4-digit form.
> >      This means that all identifiers in the spec have to lose two
> >      leading zeroes.
>
>Fixed. The description now says:
>[[
>"U+0000", "U+0001", ..., "U+FFFFFF" are Unicode based key identifiers
>([Unicode]).
>]]

okay


> > A.1: For the first two examples, there should be an explanation why
> > keydown of a capital letter produces a textInput of a lowercase
> > letter. (the example as such is correct because the embossing on the
> > key is usually upper case)
>
>Added a link to section A.1.4

okay.


> > General: There should be an example that shows how event groups can be
> > used. Otherwise, this looks like an unnecessary complication to many
> > readers.
>
>Given that this is a specification, I don't think if it is the right
>place for a tutorial on how to use groups. However, I did add a rational
>to have them in the specification:
>[[
>In general, a DOM application does not need to define and use a separate
>group unless other event listeners, external to the DOM application, may
>change the event propagation (e.g. from a concurrent DOM application,
>from imported functionalities that rely on the event system, etc.).
>]]
>
> > Key events: The CAPS LOCK key needs to be added as a modifier. This is
> > used on some Hebrew, Czech, and Swiss German keyboards.
>
>Correct. The same kind of comments could be made with keys such as
>NumLock, ScrollLock, ... We decided to introduce an extensible system
>for modifiers (for MouseEvent, KeyboardEvent):
>
>boolean getModifierState(String keyIdentifier);
>
>It will take arguments such as "Alt", "AltGraph", "CapsLock", "Control",
>"Meta", "NumLock", "Scroll", or "Shift". It returns true if the
>corresponding modifier is activated, false otherwise. The attribute
>altGraphKey, introduced in DOM 3, will be dropped. The other convenient
>attributes (ctrlKey, etc.) will remain. The init methods will contain an
>extra parameter modifiers, which is a white spaces separated list of
>modifiers, to be activated. The methods initMouseEventNS,
>initKeyboardEvent and initKeyboardEventNS will not longer have the
>parameters for the convenience attributes.

Okay (except for 'not longer' -> 'no longer' (but I don't think that's
part of the spec).



> > A.1, third example: In the PDF version (probably also PS), replace
> > љ by the actual character.
>
>Unfortunately, html2ps doesn't support the character and except stealing
>the actual shape from a converter that is able to generate it,

Is it possible to add some kind of note here in the PDF/PS versions,
so that readers don't get confused, and check the HTML? While we say
that the normative version is HTML, I guess implementers often work
from a printout.


> > A.1: Provide an example (or two contrasting ones) that shows that on
> > different architectures, it may be possible to receive different key
> > events even if the text event(s) are the same.
>
>The proposal relies on keyboard mapping, not specific
>architectures. Therefore, for the same keyboard mapping, keyboard and
>text events will be the same, independently of the architecture. No
>changes were made to the specification.

okay


> > A.1.2: Clearly say that textInput events should return data in NFC.
>
>Added:
>[[
>Characters should be normalized as defined by the Unicode normalization
>form NFC, defined in [UTR #15].
>]]

I didn't find this text. In
http://www.w3.org/2003/06/WD-DOM-Level-3-Events-20030627/keyset.html
I found:
"The sequence of keystrokes "U+0302" (Combining Circumflex Accent key) and 
"U+0045" (Latin Capital Letter E key) will likely produce (on a PC/AT 
french keyboard using a french mapping and without any modifier activated) 
the Unicode character e^ (Latin Small Letter E With Circumflex), as 
preferred by the Unicode Normalization Form NFC:"

This is not as normative as the text you propose above
(which should say who is responsible, i.e. that textInput
events should give back their text in NFC).



> > A.1.3: Pressing the "Convert" key usually will change the Hiragana
> > 'shi' (which is already visible when the user types 'i') into a kanji
> > (e.g. _ or _ or _ or _,...)
>
>Fixed.

Okay.


Regards,    Martin.

Received on Monday, 11 August 2003 12:21:02 UTC