Re: URL structure sanity check

That sounds reasonable, as long as the API Object page lays out the
information correctly ("onclick" is not supported, "click" is, for example).
Again, I am not sure, but I think WebSocket and Notification might not have
a standard event mechanism (addEventListener), but only on(x) properties.
Other objects may exist as well (I agree that this is sub optimal in terms
of the standard itself (in case this is how it is specified), or the
implementation itself (in case it is not specified this way), but this is
still the case).


☆*PhistucK*



On Tue, Nov 20, 2012 at 12:51 PM, Chris Mills <cmills@opera.com> wrote:

> On 17 Nov 2012, at 16:01, Mike Sierra <letmespellitoutforyou@gmail.com>
> wrote:
>
> > There'd be no reason for two different "click" & "onclick" pages when
> > they refer to the same thing. Or at least I hope not. The extra field
> > for access via direct handler vs listener also seems excessive. If I
> > recall, there are some marginal cases where you can do one & not the
> > other, but that just takes a sentence of text to clear up. And if most
> > events work both ways, I'd say no reason to indicate those default
> > cases.
>
> Yeah, we certainly don't need two pages. How about one page that covers
> all the different ways of utilising each event, and then we can have both
> /event and /onevent versions of each URL, with on redirecting to the other.
> I'd vote for /event being the actual page, and other terms redirecting to
> it - it has by far the largest number of hits on search engines.
>
> >
> > I was curious about any feedback on my other comments.
> > DeviceOrientation events seem naturally suited for the more
> > specialized apis/ section, but would it cause any confusion to
> > document additional Window members outside the dom/ context?  E.g.:
> > /apis/device-orientation/Window/deviceorientation
> > /apis/device-orientation/Window/devicemotion
> > /apis/device-orientation/Window/compassneedscalibration
> > Granted, the "Windows" stub could use collaping. (See below.)
> >
> > Also, there appear to be a few stray nouns such as URL schemes that I
> > don't see formally represented in the topic hierarchy
> >
> > I didn't think of the granularity issue, but Paul makes a good point.
> > Inclined to agree consolidate wherever possible to target an optimal
> > page weight or sense of context, but would hope you can still
> > faithfully represent the same level of structured data. I've only seen
> > a bit of how the system works, so let me ask if any of the following
> > might be possible for content imported according to the longer API URL
> > structure that seems to be the consensus:
> >
> > * Programmaticaly scan for member pages that contain very little
> >  content & flagging them as such?
> >
> > * Some sort of toggler allowing you to fold structured content
> >  onto the interface page, deleting the extraneous member page?
> >
> > * Can some info such as a property's data type be represented more
> >  tersely in icon form, perhaps with longer-form text as rollover?
> >
> > * Can some info be assumed away by default, such as that most events
> >  bubble?
> >
> > * Are there any other opportunities to compress info? It could be as
> >  simple as substituting "Unsupported" in the compatability tables
> >  with "NO" or a red "X". Multicolumn the see-also lists, that sort of
> >  thing.
> >
> > --Mike Sierra
> >
> > On Sat, Nov 17, 2012 at 2:34 AM, PhistucK <phistuck@gmail.com> wrote:
> >> I think there should be EventHandler properties ("onclick", when they
> exist)
> >> and events ("click", for addEventListener, also, when they exist).
> >> This can be a flag/check box on an event template, something like "Has
> an
> >> on(x) property on the object?". This information can be presented
> within the
> >> drawn Events section (name, summary, property), thus removing the need
> for
> >> creating separate pages for "onclick" and "click".
> >>
> >> ☆PhistucK
> >>
> >>
> >>
> >> On Sat, Nov 17, 2012 at 12:50 AM, Mike Sierra
> >> <letmespellitoutforyou@gmail.com> wrote:
> >>>
> >>> Scott, I was going based on some of the existing content that's
> >>> already out there. E.g., on this API page, the event names all strip
> >>> out the "on":
> >>>
> >>> http://docs.webplatform.org/wiki/apis/audio-video
> >>>
> >>> Consistency may not matter, but if they're unprefixed there's a chance
> >>> for collisions. Perhaps foo-method / foo-event is a decent alternative
> >>> to a one-way-or-the-other directive.
> >>>
> >>> --Mike Sierra
> >>>
> >>>
> >>>
> >>> On Fri, Nov 16, 2012 at 3:02 PM, Scott Rowe <scottrowe@google.com>
> wrote:
> >>>> Wait. No, that's not right, either. The onabort event handler above
> has
> >>>> been
> >>>> improperly labeled as an event.
> >>>>
> >>>> For lack of another way to do this, I've simply taken to categorizing
> >>>> event
> >>>> handlers as properties, as in
> >>>>
> >>>>
> http://docs.webplatform.org/wiki/apis/webrtc/objects/MediaStreamTrack/properties/onmute
> .
> >>>>
> >>>> This is the way the IDL treats them:
> >>>>
> >>>> interface MediaStreamTrack {
> >>>>    readonly attribute DOMString      kind;
> >>>>    readonly attribute DOMString      label;
> >>>>             attribute boolean        enabled;
> >>>>    const unsigned short LIVE = 0;
> >>>>    const unsigned short MUTED = 1;
> >>>>    const unsigned short ENDED = 2;
> >>>>    readonly attribute unsigned short readyState;
> >>>>             attribute EventHandler   onmute;
> >>>>             attribute EventHandler   onunmute;
> >>>>             attribute EventHandler   onended;
> >>>> };
> >>>>
> >>>> +SCott
> >>>>
> >>>>
> >>>>
> >>>>
> >>>> On Fri, Nov 16, 2012 at 11:38 AM, Scott Rowe <scottrowe@google.com>
> >>>> wrote:
> >>>>>
> >>>>> Oops. My example is not correct. I'll fix that. Instead, see
> >>>>> http://docs.webplatform.org/wiki/apis/file/events/onabort.
> >>>>> +SCott
> >>>>>
> >>>>>
> >>>>>
> >>>>> On Fri, Nov 16, 2012 at 11:30 AM, Scott Rowe <scottrowe@google.com>
> >>>>> wrote:
> >>>>>>
> >>>>>> Hi Mike,
> >>>>>>
> >>>>>> Perhaps I'm not gettin' it, but why would you strip out the "on"? We
> >>>>>> usually document them as event handlers (properties). Here's an old
> >>>>>> MDN doc:
> >>>>>> https://developer.mozilla.org/en-US/docs/DOM/FileReader, and
> here's my
> >>>>>> treatment of
> >>>>>>
> >>>>>>
> http://docs.webplatform.org/wiki/apis/webrtc/objects/MediaStreamTrack/properties/onmute
> .
> >>>>>>
> >>>>>> +Scott
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>> On Fri, Nov 16, 2012 at 4:49 AM, Jonathan Garbee <
> jonathan@garbee.me>
> >>>>>> wrote:
> >>>>>>>
> >>>>>>> I'm inclined to agree with Paul here.  Using his example of
> >>>>>>> PerformanceTiming there are about *twenty* subpages.  That seems
> >>>>>>> pretty
> >>>>>>> excessive to me.  I think his idea of using one comprehensive page
> is
> >>>>>>> good,
> >>>>>>> but making sure headings are setup properly so if people want to
> >>>>>>> point to a
> >>>>>>> specific thing or know where they are going they can easily use a
> >>>>>>> fragment
> >>>>>>> to do it.  I'm also seeing some with only two or three subpages;
> >>>>>>> having
> >>>>>>> those seems almost wasted for so little content when one page could
> >>>>>>> do just
> >>>>>>> fine with the information.
> >>>>>>>
> >>>>>>> I am not sure what was said during the telcon for this though.  If
> >>>>>>> there
> >>>>>>> was a technical reason for wanting to use sub-pages then please let
> >>>>>>> me know.
> >>>>>>> I think we could get the forms/templates setup pretty well for
> having
> >>>>>>> one
> >>>>>>> page handle all that is needed though.
> >>>>>>>
> >>>>>>> -Garbee
> >>>>>>>
> >>>>>>>
> >>>>>>> On 11/15/2012 6:33 PM, Paul Irish wrote:
> >>>>>>>
> >>>>>>> I've long proposed shorter URLs and still think they are a better
> >>>>>>> match
> >>>>>>> for our audience than over-specifying and using spec vocabulary.
> >>>>>>>
> >>>>>>> However,
> >>>>>>>
> >>>>>>> Given this list, I feel like the larger issue is one of
> granularity.
> >>>>>>> There simply isn't a good reason all  the PerformanceTiming events
> >>>>>>> (for
> >>>>>>> example) should get their own page. performance.timing deserves ONE
> >>>>>>> page
> >>>>>>> that's comprehensive.
> >>>>>>>
> >>>>>>> Our imported content defined these conventions, though, as far as I
> >>>>>>> know, no one considered them. In nearly every page in the linked
> >>>>>>> file, I
> >>>>>>> would probably collapse it into its parent.
> >>>>>>>
> >>>>>>> I don't think we'll find an URL structure that is consistent,
> >>>>>>> technically accurate, using precise terminology, using developer
> >>>>>>> terminology, and simultaneously user-friendly. And that's okay. The
> >>>>>>> important thing is having high-value documentation. Pages that
> >>>>>>> developers
> >>>>>>> read and are hugely impressed so much valuable content is there.
> >>>>>>>
> >>>>>>>
> >>>>>>> On Thu, Nov 15, 2012 at 10:51 PM, Michael Sierra <
> msierra@adobe.com>
> >>>>>>> wrote:
> >>>>>>>>
> >>>>>>>> Turns out there are quite a few collisions in these examples once
> >>>>>>>> you
> >>>>>>>> strip out the 'on' prefixes from the event names:
> >>>>>>>>
> >>>>>>>> /apis/file/FileReader/abort
> >>>>>>>> /apis/file/FileReader/error
> >>>>>>>> /apis/push/PushService/error
> >>>>>>>> /apis/webcrypto/CryptoOperation/abort
> >>>>>>>> /apis/webcrypto/CryptoOperation/complete
> >>>>>>>> /apis/webcrypto/CryptoOperation/init
> >>>>>>>> /apis/webrtc/DataChannel/close
> >>>>>>>> /apis/websocket/WebSocket/close
> >>>>>>>>
> >>>>>>>> --Mike Sierra
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>> ________________________________________
> >>>>>>>> From: PhistucK [phistuck@gmail.com]
> >>>>>>>> Sent: Thursday, November 15, 2012 5:33 PM
> >>>>>>>> To: Michael Sierra
> >>>>>>>> Cc: public-webplatform@w3.org
> >>>>>>>> Subject: Re: URL structure sanity check
> >>>>>>>>
> >>>>>>>> In some cases (WebSocket, for example, if I am not mistaken), you
> >>>>>>>> cannot use addEventListener for listening to an event, like
> >>>>>>>> ws.onopen.
> >>>>>>>> Adding it as "open" might cause some confusion.
> >>>>>>>> It might be an implementation issue, because I think WebSocket is
> >>>>>>>> specified to subclass EventTarget as well, which means
> >>>>>>>> addEventListener
> >>>>>>>> should apply to it, but in Chrome, as far as I remember, it does
> not
> >>>>>>>> work. I
> >>>>>>>> have not tried other browsers.
> >>>>>>>> Anyway, in cases like these (assuming no browser implements
> >>>>>>>> addEventListener for that object), events should begin with the
> "on"
> >>>>>>>> prefix,
> >>>>>>>> I believe (but still have the regular Event template, I guess).
> >>>>>>>>
> >>>>>>>> What does everyone think?
> >>>>>>>>
> >>>>>>>> Also, does anyone have any information regarding other browsers
> (or
> >>>>>>>> current Chrome?) in this regard?
> >>>>>>>>
> >>>>>>>>
> >>>>>>>> ☆PhistucK
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>> On Thu, Nov 15, 2012 at 11:18 PM, Michael Sierra
> >>>>>>>> <msierra@adobe.com<mailto:msierra@adobe.com>> wrote:
> >>>>>>>> Re the recent conf-call clarifying the apis/ URL space, here are a
> >>>>>>>> few
> >>>>>>>> random APIs generated from some test W3C specs:
> >>>>>>>>
> >>>>>>>> https://github.com/mike-sierra/webplatform/blob/master/urls.txt
> >>>>>>>>
> >>>>>>>> Of all the comments are marked "#",
> >>>>>>>>
> >>>>>>>> * I think of "deviceorientation" as belonging under apis/, but it
> >>>>>>>> seems
> >>>>>>>> to simply modify the window object.  Can/should it be represented
> >>>>>>>> here?
> >>>>>>>>
> >>>>>>>> * The File API defines a new URL scheme, and I wonder where that
> >>>>>>>> gets
> >>>>>>>> doc'ed
> >>>>>>>>
> >>>>>>>> * I noticed one instance of a namespace collision, where an
> abort()
> >>>>>>>> method collides with an "abort" event.  In this URL list, I kept
> it
> >>>>>>>> as it
> >>>>>>>> appears in the spec, "onabort," but current practice in the wiki
> is
> >>>>>>>> to strip
> >>>>>>>> the "on" prefix, which would cause a problem.
> >>>>>>>>
> >>>>>>>> --Mike Sierra
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>
> >>>>>
> >>>>
> >>>
> >>
>
>