Re: URL structure sanity check

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

Received on Tuesday, 20 November 2012 10:52:21 UTC