W3C home > Mailing lists > Public > public-webplatform@w3.org > November 2012

Re: URL structure sanity check

From: Scott Rowe <scottrowe@google.com>
Date: Fri, 16 Nov 2012 12:02:53 -0800
Message-ID: <CAHZLcPpBpHK3JGh=m=ACB-LV48GULh3sW5kCmmkbpWndHi+usQ@mail.gmail.com>
To: Jonathan Garbee <jonathan@garbee.me>
Cc: "public-webplatform@w3.org" <public-webplatform@w3.org>
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<https://github.com/mike-sierra/webplatform/blob/master/urls.txt>,
>>> 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 20:03:21 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 8 May 2013 19:57:35 UTC