- From: Doug Schepers <schepers@w3.org>
- Date: Tue, 25 Nov 2014 10:26:33 -0500
- To: timeless@gmail.com, public-pointer-events@w3.org
Hi, Timeless–
Thanks for this review.
This is good feedback on typos, structural issues, general readability
and other non-normative or editorial issues. We will certainly try to
address these issues in a timely way.
It seems like you may have a couple of substantive technical comments
(#31, for example), but it wasn't clear to me if they were stylistic or
if you're suggesting specific technical changes.
If you wouldn't mind, we'd really appreciate if you would isolate any
normative issues or changes you're requesting as separate emails, and
include a suggestion as to what would satisfy your concern.
p.s. These are the times I really wish we had the spec annotator working
today!
Thanks!
-Doug
On 11/16/14 1:29 AM, timeless@gmail.com wrote:
> 1. I can't link to the examples, please give them ids.
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#widl-PointerEvent-pointerType
>
>
>> See Example 2 for a basic demonstration of how the pointerType can
>> be used.
>
> That really wants to link to example 2, but it can't, so it doesn't.
>
> 2. cancell?able:
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#h2_examples
>
>> EXAMPLE 4: Firing an untrusted pointer event from script var event
>> = new PointerEvent("pointerover", {bubbles: true, cancelable:
>> true,
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#h4_firing-events-using-the-pointerevent-interface
>
>
>> Initialize the cancelable attribute for the event to true if the
>> event name is
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#h4_list-of-pointer-events
>
>
>> Cancellable
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#h_note_20
>
>> Touch manipulations are intentionally not a default action of
>> pointer events. Removing this dependency on the cancellation of
>> events facilitates performance optimizations by the user agent.
>
> 3. spellcheck
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#process-pending-pointer-capture
>
>
>> and the hit test node has recieved [sic] pointerover
>
> 4. w3 is en-us
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#h3_implicit-pointer-capture
>
>
>> Some user agents implement their own implicit pointer capture
>> behaviour [en-gb]
>
> Note that the document also includes the correct spelling
> (behavior(s)) -- including in the outline.
>
>
> 5. like/or/a
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#h2_abstract
>
>> This document defines events and related interfaces for handling
>> hardware agnostic pointer input from devices like a mouse, pen, or
>> touchscreen.
>
> There are a couple of problems with "like"/"or" a. "like" implies
> "like, but not actually", so you're defining events for things that
> are similar to mouse/pen/touchscreen, but don't actually include
> mouse/pen/touchscreen. b. "or" bothers me. You should really want to
> use "and" in your list. or end it with "etc." c. there's an article
> "a" for mouse, but you aren't really saying "like a specific mouse",
> you mean mice in general.
>
> I'd probably replace "like" with "including", drop "or" entirely, and
> add "etc." to the end.
>
> ... handling input in a device agnostic way from hardware including
> mouse, pen, touchscreen, etc.
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#intro
>
>> Newer computing devices today, however, incorporate other forms of
>> input, like touchscreens or pen input.
>
> Same objections to like/or
>
> 6. "other than mouse" is awkward.
>
>> For compatibility with existing mouse based content, this
>> specification also describes a mapping to fire [DOM-LEVEL-3-EVENTS]
>> Mouse Events for pointer device types other than mouse.
>
> "other than mouse" is awkward.
>
> ... for other pointer device types.
>
> -- as an asside, I need to ask the Process TF to consider that WGs
> shouldn't be allowed to claim a document has satisfied technical
> requirements if it hasn't been run through a spell checking program.
> --
>
> 7. step function
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#intro
>
>> However, that approach requires a step function in opportunity cost
>> to authors when adding support for a new input type.
>
> This is an introduction, but i have no idea what a "step function" is
> here. Ideally your introduction should be in plain English. Note that
> I consider "opportunity cost" to be understandable.
>
>> A pointer can be any point of contact on the screen made by a mouse
>> cursor, pen, touch (including multi-touch), or other pointing input
>> device.
>
> What if there is no point of contact?
>
> (Perhaps it's referential only)
>
> 8. necessary
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#intro
>
>> The primary goal is to provide a single set of events and
>> interfaces that allow for easier authoring for cross-device pointer
>> input while still allowing for device-specific handling when
>> necessary.
>
> I object to "necessary", how about "when an author insists on being
> stubborn and not forward looking to the exclusion of other input
> methods". (It's ok to drop the end of this correction, but I'd hope
> that the spirit of my suggestion can be incorporated.)
>
>> only where necessary to get the best experience.
>
> s/the best/an augmented/
>
>
> 9. this paragraph is hiding important "key goals" in a rather long
> paragraph. that's unfortunate, they should really be bulleted.
>
>> An additional key goal is to enable multi-threaded user agents to
>> handle default touch actions, such as scrolling, without blocking
>> on script execution.
>
> 10. active pointer
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#dfn-active-pointer
>
>
>> In some platforms, the set of active pointers includes all pointer
>> input to the device, including any that are not targeted at the
>> user agent (e.g. another application).
>
> s/In/On/ s/another application/those targeted at (captured by?) other
> applications/
>
> 11. digitizer
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#dfn-digitizer
>
>> Most commonly, this is the surface that sense input from touch
>> contact or a pen stylus.
>
> s/sense/senses/ s/from/from the/
>
> 12. unique
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#widl-PointerEvent-pointerId
>
>
>> This identifier must be unique from all other active pointers at
>> the time.
>
> What is the scope of uniqueness here? Can two UAs on two unrelated
> devices share a pointerId? Can one UA assign the same pointerId to
> differrent objects when reporting to two disconnected web pages?
>
> 14. pressure
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#widl-PointerEvent-pressure
>
>
>> the value must be 0.5 when in the active buttons state and 0
>> otherwise.
>
> please mark up "active buttons state"
>
> 15. tiltX
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#widl-PointerEvent-tiltX
>
>
>> The plane angle (in degrees, in the range of [-90,90]) between the
>> Y-Z plane and the plane containing both the transducer (e.g. pen
>> stylus) axis and the Y axis.
>
> suppose i have a gyroscope and accelerometer augmented "air" pen (you
> could imagine turning a mobile phone into such a device). There's no
> "transducer", but it certainly has a tilt.
>
> 16. insufficiently labeled figure 2
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#fig-positive-tiltx.x
>
> the figure does not identifier "front" of the "transducer" (or any
> other orientation) -- it should label thins like "positive x" or
> "positive y".
>
> 17. missing period
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#dfn-fire-an-event-named-e
>
>
>> * Set the relatedTarget attribute of the event to null * Fire the
>> event to the pointer capture target override object.
>
> 18. too complicated
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#process-pending-pointer-capture
>
>
>> Further, if the pointer capture target override is not set, the
>> pending pointer capture target override is not equal to the hit
>> test node for the pointer event which invoked this process,
>
> It's too hard to read this sentence to the end. You could either add
> an "and" after "set, ", or turn the item into a bulleted list of
> conditions.
>
>> and the hit test node has recieved pointerover and pointerenter
>> events, then fire a pointer event named pointerout and a pointer
>> event named pointerleave at the hit test node.
>
> 19. table comments
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#list-of-pointer-events
>
>
>> Trusted proximal event target types Event object interface
>
> The values are the same in these columns for all rows. If this table
> is related to a table outside this document, there should be a
> reference to it. If there isn't such a table, can you remove the
> column?
>
>> Varies: when the pointer is primary, all default actions of
>> mouseover
>
> a. I don't understand what this means. b. This item doesn't end with
> a period.
>
>> Varies: when the pointer is primary, all default actions of the
>> mousedown event.
>
> This similar sounding item includes a period.
>
>> Cancelling this event also sets the PREVENT MOUSE EVENT flag for
>> this pointerType, which prevents subsequent firing of certain
>> compatibility mouse events.
>
> 20. Unclosed paren
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#list-of-pointer-events
>
>
>> In the case of the primary pointer, these events (with the
>> exception of gotpointercapture, and lostpointercapture may also
>> fire compatibility mouse events.
>
> 21. touch mismatch w/ mouse
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#the-pointerdown-event
>
>
>> For mouse, this is when the device transitions from no buttons
>> depressed to at least one button depressed. For touch, this is when
>> physical contact is made with the digitizer.
>
> Mouse is clearly not going to fire for the second button down.
>
> If I put one finger to the digitizer, it will fire. If I put another
> finger to the digitizer, it appears that the instructions here will
> result in it firing, which seems to be different from mouse.
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#the-pointerup-event
>
>
>> For mouse, this is when the device transitions from at least one
>> button depressed to no buttons depressed. For touch, this is when
>> physical contact is removed from the digitizer.
>
> 22. Missing word
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#the-pointercancel-event
>
>
>> After having fired the pointerdown event, the pointer is
>> subsequently used to manipulate the page viewport (e.g. panning or
>> zooming).
>
> "event, the" -> "event, if the"
>
> 23. confusing
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#the-pointercancel-event
>
>
>> Examples of scenarios in which a user agent might determine that a
>> pointer is unlikely to continue to produce events include:
>
>> The user inputs a greater number of simultaneous pointers than is
>> supported by the device.
>
> How can a useragent discover this??
>
> 24. mising periods
>
>
>> A user agent must fire a pointer event named pointercancel in the
>> following circumstances: * The user agent has determined that a
>> pointer is unlikely to continue to produce events (for example,
>> because of a hardware event). * After having fired the pointerdown
>> event, the pointer is subsequently used to manipulate the page
>> viewport (e.g. panning or zooming).
>
> Note the periods here.
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#the-pointerout-event
>
> A user agent must fire a pointer event named pointerout when any of
> the following occurs:
>> A pointing device is moved out of the hit test boundaries of an
>> element After firing the pointerup event for a device that does not
>> support hover (see pointerup) After firing the pointercancel event
>> (see pointercancel) When a pen stylus leaves the hover range
>> detectable by the digitizer
>
> Note the lack of periods here.
>
> 25. off/out-of
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#the-pointerleave-event
>
>
>> A user agent must fire a pointer event named pointerleave when a
>> pointing device is moved off of the hit test boundaries of an
>> element and all of its descendants,
>
> off -> out of ?
>
> 26. broken table
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#widl-Element-setPointerCapture-void-long-pointerId
>
> .prmNullFallse has a rule for text-align:center which cauess the x's
> to appear "centered" across a column.
>
> Unfortunately, nothing constrains the table width, and nothing
> constrains the column width. When the document is in a maximized
> browser, the x is so far away from the label (Nullable), or the next
> label (Optional), that it just appears to be floating.
>
> Fixes: Either constrain the width of the column, or don't use center
> as alignment. You could constrain the table, but I wouldn't suggest
> that.
>
> 27. overly strong must
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#widl-Element-setPointerCapture-void-long-pointerId
>
>
>> Subsequent events for the pointer must always be targeted at this
>> element.
>
> This implies "forever", you need to say "until canceled" or "until
> {something}"
>
> 28. Too long, can't process
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#widl-Element-setPointerCapture-void-long-pointerId
>
>
>> Sets pointer capture for the pointer identified by the argument
>> pointerId to the element on which this method is invoked.
>> Subsequent events for the pointer must always be targeted at this
>> element. The pointer must be in its active buttons state for this
>> method to be effective, otherwise it fails silently. Throws a
>> DOMException with the name InvalidPointerId when the provided the
>> method's argument does not match any of the active pointers.
>
> It's true that Pointer Capture defines this, but, this really isn't
> helpful. And the fact that what's important is hidden in an empty
> note ("See Pointer Capture") doesn't help either.
>
> There should be a link to h3_setting-pointer-capture
>
> 29. the provided the method's -- the the the the
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#widl-Element-setPointerCapture-void-long-pointerId
>
>
http://www.w3.org/TR/2014/WD-pointerevents-20141113/#widl-Element-releasePointerCapture-void-long-pointerId
>
>> Throws a DOMException with the name InvalidPointerId when the
>> provided the method's argument does not match any of the active
>> pointers.
>
> 1. drop the "the" after "provided". 2. make everyone's life better by
> using "pointerId" instead of not naming the argument.
>
> 30. is
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#widl-Navigator-maxTouchPoints
>
>
>> For example, suppose a device has 3 touchscreens, which support 2,
>> 5, and 10 simultaneous touch contacts, respectively. The value of
>> maxTouchPoints is 10.
>
> is -> should be (or something)
>
> 31. what happens if...
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#widl-Navigator-maxTouchPoints
>
>
>> The maximum number of simultaneous touch contacts supported by the
>> device. In the case of devices with multiple digitizers (e.g.
>> multiple touchscreens), the value must be the maximum of the set of
>> maximum supported contacts by each individual digitizer.
>
>> maxTouchPoints is often used to ensure that the interaction model
>> of the content can be recognized by the current hardware. UI
>> affordances can be provided to users with less capable hardware. On
>> platforms where the precise number of touch points is not known,
>> the minimum number guaranteed to be recognized is provided.
>> Therefore, it is possible for the number of recognized touch points
>> to exceed the value of maxTouchPoints.
>
> Suppose a user has an attached touchpad which supports 5
> touchpoints. Suppose the user only uses their mouse and is unaware of
> this touchpad (it could be physically obscured).
>
> There doesn't appear to be any authoring guidelines that they should
> be aware that just because some input method MAY support
> maxTouchPoints, doesn't mean that the user will be able to.
>
> Suppose that I have a phone which supports 5 touchpoints, and I'm
> using a screen reader.
>
> The mode of the screen reader involves replacing the standard input
> method with a method whereby there are at most 1 touch points
> accessible to the web page (I believe, I haven't actively
> investigated, but let's just suppose I'm right). Should the UA report
> 1 or 5 for maxTouchPoints? (The UA does know that the screen reader
> is active, and it knows how the screen reader controls the UA.)
>
> 32. period
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#h3_the-touch-action-css-property
>
>
>> Applies to: all elements except: non-replaced inline elements,
>> table rows, row groups, table columns, and column groups
>
> no period...
>
>> Computed value: Same as specified value.
>
> period...
>
> 33. stray space
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#h4_the-primary-pointer
>
>
>> Authors who desire single-pointer interaction can achieve this by
>> ignoring non-primary pointers (however, see the note below on
>> multiple primary pointers) .
>
> the space after the closing paren is extraneous.
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#h3_the-touch-action-css-property
>
>
>> The touch-action property only applies to elements that support
>> both the CSS width and height properties (see [CSS21] ).
>
> the space before the closing paren is extraneous.
>
> 34. huh?
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#the-touch-action-css-property
>
>
>> During the execution of a behavior, the user agent must not fire
>> subsequent pointer events for the pointer.
>
> I'm not sure what a "behavior" is here. Do you mean "an intrinsic
> user-agent behavior"?
>
> 35. missing space
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#implicit-release-of-pointer-capture
>
>
>> Immediately after firing the pointerup or pointercancel events, a
>> user agent must run the steps as if the releasePointerCapture()
>> method has been called with an argument equal to the pointerId
>> property of the pointerup orpointercancel event just dispatched.
>
> there's a space missing after 'or'.
>
> 36. missing conditional
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#implicit-release-of-pointer-capture
>
>
>> Immediately after firing the pointerup or pointercancel events, a
>> user agent must run the steps as if the releasePointerCapture()
>> method has been called with an argument equal to the pointerId
>> property of the pointerup orpointercancel event just dispatched.
>
> If I don't call Element.setPointerCapture() and a user clicks and
> releases, it sounds like the UA must process releasePointerCapture.
>
> Here are the steps:
>
>> 1. If the pointerId provided as the method's argument does not
>> match any of the active pointers, then throw a DOMException with
>> the name InvalidPointerId.
>
> It won't be active, I think. So now the UA must throw a
> DOMException?
>
> 37. When, not If
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#implicit-release-of-pointer-capture
>
>
>> If the pointer capture target override is removed from the document
>> tree, clear the pending pointer capture target override and pointer
>> capture target override nodes and fire a Pointer Event named
>> lostpointercapture at the document.
>
> If -> When
>
> 38. Pointer Event or PointerEvent ??
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#implicit-release-of-pointer-capture
>
>
>> If the pointer capture target override is removed from the document
>> tree, clear the pending pointer capture target override and pointer
>> capture target override nodes and fire a Pointer Event named
>> lostpointercapture at the document.
>
> There are 89 instances of "pointer event" (case insensitive), and 40
> of "PointerEvent" (case sensitive).
>
> This case seems to be one where the latter is more appropriate.
>
> 39. Document or document?
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#implicit-release-of-pointer-capture
>
>
>> If the pointer capture target override is removed from the document
>> tree, clear the pending pointer capture target override and pointer
>> capture target override nodes and fire a Pointer Event named
>> lostpointercapture at the document.
>
> should `document` be a linked thing, or something something...
>
> 40. the/may
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#dfn-compatibility-mouse-events
>
>
>> The vast majority of web content existing today codes only to Mouse
>> Events. The following describes the algorithm for how a user agent
>> may map generic pointer input to mouse events for compatibility
>> with this content.
>
> If this is a way for something to happen, then perhaps there are
> other ways in which it may happen. In which case it should not say
> "the alogrithm", but rather "an algorithm".
>
> If this should be the only way, then you'll need to rephrase:
>
> "If a UA wishes to ... then it SHOULD use the following algorithm
> ..."
>
> 41. some cases
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#compatibility-mapping-with-mouse-events
>
>
>> The relative ordering of these high-level events (click,
>> contextmenu, focus, blur, etc.) with pointer events is undefined
>> and varies between user agents. For example, in some user agents
>> contextmenu will often follow a pointerup, in others it'll often
>> precede a pointerup or pointercancel, and in some situations it may
>> be fired without any corresponding pointer event.
>
> Probably worth noting that it could be fired because of a keyboard
> key (the context menu key, or shift-f10). Yes somewhere else you
> mentioned keyboards, but it's worth mentioning it again.
>
> 42. link and anchor support-hover/do-not-support-hover
>
> there are lots of mentions of "does not support hover", there are
> anchors:
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#mapping-for-devices-that-support-hover
>
>
http://www.w3.org/TR/2014/WD-pointerevents-20141113/#mapping-for-devices-that-do-not-support-hover
>
> but, things don't link to them:
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#the-pointerover-event
>
>
>> A user agent must fire a pointer event named pointerover when a
>> pointing device is moved into the hit test boundaries of an
>> element. A user agent must also fire this event prior to firing a
>> pointerdown event for devices that do not support hover (see
>> pointerdown).
>
> 43. missing periods?
>
> http://www.w3.org/TR/2014/WD-pointerevents-20141113/#h3_mapping-for-devices-that-do-not-support-hover
>
>
>> * The input can hover independently of activation (e.g. moving a
>> mouse cursor without any buttons pressed) * The input will likely
>> produce the mousemove event on an element before clicking it
> -- This review was sent in response to:
> http://lists.w3.org/Archives/Public/public-review-announce/2014Nov/0002.html
>
>
>
Received on Tuesday, 25 November 2014 15:26:41 UTC