Re: URL structure sanity check

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 Friday, 16 November 2012 22:51:15 UTC