Re: URL structure sanity check

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.

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

Received on Saturday, 17 November 2012 16:01:28 UTC