- From: timeless <timeless@gmail.com>
- Date: Wed, 7 Dec 2011 16:29:25 -0500
- To: public-geolocation@w3.org
http://www.w3.org/TR/2011/WD-orientation-event-20111201/
> The first DOM event provided by the specification,
s/by the/by this/
> A user facing a compass heading of alpha degrees is holding the device in their hand,
> with the screen in a vertical plane and the top of the screen pointing to their right.
> The orientation of the device is:
> {alpha: 270 - alpha,
This is confusing, you should use a variable like r. Or at least
colorized alpha differently from alpha:. Note that some people read
documents on monochrome/monofont rendering displays, so using distinct
names for the property and the variable is preferable.
> Registration for, and firing of the deviceorientation event must follow the usual behavior of DOM Level 2 Events, [DOMEVENTS].
I wonder if we have better language to mean "for DL2E or its
successor". (Referencing Level 2 seems annoying in generally.)
> interface DeviceOrientationEvent : Event {
> readonly attribute double? alpha;
please indent things inside braces more than the line that declares
the brace. Four spaces would be nice, but whatever you generally use
would be acceptable.
> void initDeviceOrientationEvent(in DOMString type,
This is not the way future events are supposed to be declared in DOM4 (?)....
> In addition, when a new listener registers for the event, implementations should fire the event as soon as sufficiently fresh data is available.
This seems to indicate that other listeners might get an additional
event that they might not have otherwise received when new listeners
are registered...
> Thus the angles alpha, beta and gamma form a set of intrinsic Tait-Bryan angles of type Z-X'-Y''. [EULERANGLES] Note
I think that it would be best if the `[]` was before the `.` (see your
use of `[DOMEVENTS]` above).
> that this choice of angles follows mathematical convention, but means that alpha is in the opposite sense to a compass heading. It also means that the angles do not match the roll-pitch-yaw convention used in vehicle dynamics.
> If an implementation can never provide orientation information, the event should be fired with all properties set to null.
absolute isn't nullable, but is part of `all properties`.
> User agents ... provide a new DOM event
I'm not a fan of `new DOM event`, what does `new` mean, and why is it needed?
> defined in the DOM Level 2 Events specification [DOMEVENTS].
I don't see much value in repeatedly saying "DOM Level 2 Events
specification [DOMEVENTS]", could you drop "DOM Level 2 Events
specification" and just use "[DOMEVENTS]", that makes updating the
spec later to some other specification easier.
Also note that you aren't consistent, as below you omit
'specification' for unknown reasons:
> ... follow the usual behavior of DOM Level 2 Events [DOMEVENTS].
> Furthermore, user agents should only fire the event if calibrating the compass will increase the accuracy of the data provided by the deviceorientation event.
`will` is problematic, is `could` ok? predicting whether a user will
be helpful when asked to calibrate a device seems unreasonable.
> The default action of this event should be for the user agent to present the user with details of how to calibrate the compass.
`details` is awkward, are you opposed to "instructions"?
> The event must be cancelable, so that web sites can provide their own alternative calibration UI.
If I design a headless device (i.e. one without a display), and I want
to support this specification, should I just violate this must?
> 4.3 devicemotion Event
this is still yet another way of writing `d2e spec [ref]` (note the
extra comma):
> the usual behavior of DOM Level 2 Events, [DOMEVENTS].
> User agents must also provide an event handler IDL attribute [HTML5]
shouldn't some of `event handler idl attribute` be in some markup?
> [Callback, NoInterfaceObject]
I think webidl should require specs that use NoInterfaceObject to
justify it. I wonder if this should be a Dictionary instead.
> The acceleration must be expressed in m/s^2.
Please consider using either m/s², m/s<sup>2</sup>, m/(s^2) or <mathml>....
could you please mark up the units somehow:
> expressed in deg/s.
> expressed in milliseconds.
> It must be a constant, to simplify filtering of the data by the Web application.
s/It/The interval/
What if the system doesn't do realtime sampling?
> 5 Use-Cases and Requirements
You're missing a note that this section is non-normative.
And you could really benefit from a note indicating that these are
use-cases/requirements to the specification and not to consumers of
the specification.
> 5.1.2 Gesture recognition
> A Web application monitors the device's acceleration and applies signal processing in order to recognize certain specific gestures.
s/specific/coarse/
> For example, using a shaking gesture to clear a web form.
> Worked Example
> This section is non-normative.
This section is missing a section number in IE9.
> If r represents this vector in the rotated device body frame xyz, then r is as follows.
Please consider using <MathML>, I can't see whatever you put here.
> If R resresents the vector r in the earth frame XYZ, then since the inital body frame is aligned with the earth, R is as follows.
resresents isn't a word, please use a spell checker.
Received on Wednesday, 7 December 2011 21:29:55 UTC