Re: I18N last call comments on DOM 3 Events

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

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

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

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

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

> 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 Dürst 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.
]]

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

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

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

> 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 [...].
]]
 
> 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".
]]

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

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

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

> 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

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


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

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

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

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

Philippe

Received on Thursday, 3 July 2003 15:28:21 UTC