Open littledan opened 6 years ago
Generally these types are used by tons of web specs, not just HTML. In general I think having Web IDL be a foundational document for many web specs (including JavaScript), each of which only uses a subset of Web IDL, is a reasonable way to go.
Things that are truly HTML-specific, like [CEReactions] or [HTMLConstructor], are indeed defined in HTML.
OK, what about having a third document, "IDL types for the Web Platform"?
What is the motivation? As I said, I think having Web IDL be a foundational document for many web specs (including JavaScript), each of which only uses a subset of Web IDL, is a reasonable way to go.
JavaScript is not special in this regard; e.g. Fullscreen only uses a subset of Web IDL, just like JavaScript would, but we don't ask for special factoring and new documents created so that Fullscreen can avoid a dependency on those parts it doesn't use.
JavaScript is not special in this regard; e.g. Fullscreen only uses a subset of Web IDL, just like JavaScript would, but we don't ask for special factoring and new documents created so that Fullscreen can avoid a dependency on those parts it doesn't use.
I think parts of the node.js folks see this differently.
In the ECMAScript spec, we're currently sticking to a bunch of unstated conventions about how things are exported. I think TC39 will probably be sticking to these. It would be nice to have these somehow documented. If we're pulling in all of WebIDL as it currently is, then we should probably document the limitations some other way.
The other concern is that I expect TC39 to have would be linking JavaScript too tightly to the Web Platform. This isn't just about Node.js; there are lots of uses of JS outside of the web, and the committee is interested in this goal in an abstract way as well as how it relates to Node.js. If we depend on something that normatively references the web platform, or is even just very big and unnecessarily complex for the application, I expect some committee members to be skeptical of the whole thing (even as much as I have my bias of caring more about the web platform personally).
In my opinion, it makes sense for TC39 to adopt some kind of IDL even if we couldn't get the benefits of synergy with WebIDL. If WebIDL can work, that's excellent and the best case; if it won't work here for any reason (such as inappropriate coupling, or syntax that's considered too unfriendly, or missing features), I think it'd still be a benefit to TC39 to use some other IDL-like thing. I've filed this issue and #484 #485 in order to explore ways to try to make WebIDL acceptable for TC39.
I still can't see the concrete concern, or reason why the JS spec is different from the Fullscreen spec in that both use subsets of Web IDL.
I don't understand what's unclear about a layering concern. If ECMAScript normatively references WebIDL, and WebIDL includes things that are just for the web platform, then it creates the sense that ECMAScript only makes sense in the web platform.
I don't think that conclusion follows from that premise. E.g. URL works perfectly fine even on a platform that does not define DOMException, but it still normatively references Web IDL.
Perhaps you have some conception that documents which normatively reference each other require implementing the entire other document? That's not generally how we operate in the standards world; instead you only have to implement the parts that are directly referenced (e.g. via hyperlinks).
I theorize that the subset of WebIDL we'd want for 262 is small enough relative to all of WebIDL that the benefits of @littledan's proposed layering will be pretty nice in terms of clarity and understandability. It also serves as a nice way to document the subset of WebIDL in use.
I think you're arguing different things. What @littledan talks about is essentially a perception issue, imho. Engineers are surprisingly prone to be affected by such things given how rational they claim to be. I found that taking that in account can often help move things forward.
One concern I have is that if we also change IDL to depend on Infra (as is the plan and already done to some extent) we'll have the same discussion there to create a subset of Infra for the bits only IDL needs.
And although you have helped with the aesthetics for some consumers, you've made it harder for lots of other folks to contribute and understand what's going on.
(I do think it's worth exploring though and see if we can get somewhere satisfactory.)
Yes, I can see things getting more difficult to read if it's all split up into multiple documents in an obscure way. Maybe we could mark things as "level 1"/"level 2" within the same document, and ECMAScript can depend on the "level 1" stuff?
I'd probably go with "Core" and "Extended" or some such, but yeah, that could work.
Kindly please no. We have enough trouble with the W3C TR “version 1” confusing everyone, and tracking this version also.
@littledan said:
Maybe we could mark things as "level 1"/"level 2" within the same document, and ECMAScript can depend on the "level 1" stuff?
Oh, let's not create yet more semantics for levels. :D
@annevk said:
I'd probably go with "Core" and "Extended" or some such, but yeah, that could work.
Maybe we should just spell out the layering and see what it would look like, e.g.:
Infra
|
IDL (core)
|
ES6
|
IDL (extended) <—> HTML
|
Web specs
Core and extended could work better - so long as it’s clearly specified as to why the split.
@annevk said:
One concern I have is that if we also change IDL to depend on Infra (as is the plan and already done to some extent) we'll have the same discussion there to create a subset of Infra for the bits only IDL needs.
I don't think that's necessarily going to be the case. Remember that the goal of this layering is twofold: 1) help explain how the different specs build on each other, and thus help inform decisions as to where to put new stuff, and 2) manage sensibilities.
While I do thing splitting up WebIDL into an ES specific is necessary for (2), I don't think anyone will care about the underlying infra stuff—it's just less visible, and also: not syntax (again irrational arguments, but…).
Sorry, the "level" wording was clumsy; I am imagining something like multiple headings in the same document. I like core/extended better, and was definitely not intending to say that core would be "v1" and extended "v2".
There are some details to work out for where we'd want to put the split, but I'd say that "extended" would include things that we think of as "legacy" and web platform-specific things that we don't expect to be in common with other uses of JavaScript.
About the infra document in particular: Maybe we could upstream more parts of the infra document that make sense in pure ES into the ES spec.
About the infra document in particular: Maybe we could upstream more parts of the infra document that make sense in pure ES into the ES spec.
This is precisely why we need to agree on the layering. Your comment makes me think we don't have the same layering in mind.
I don't really see how we can have an IDL (core) -> ES6 layering. What I might be able to imagine is a layering like ES (core) -> IDL (core) -> ES (standard library), or alternatively, IDL (core) and ES6 call out to each other freely. The ES spec isn't currently broken out with a separate "standard library" component, but it could be.
Where would the ES binding be? In IDL (extended)?
Maybe we could upstream more parts of the infra document that make sense in pure ES into the ES spec.
Infra is meant to be higher-level and also provides concepts useful for specifications that don't depend on JavaScript per se.
ES (core) -> IDL (core) -> ES (standard library)
Well, technically WebIDL is language agnostic. So it really belongs right after infra in the layering. The bindings though would sit somewhere after ES (core), though. And the Web specific IDL, probably after ES (stdlib), no?
In this thread, I think we're discussing the need for an identified subset of WebIDL, including bindings to ES, which doesn't reference HTML. In my above post, I was including both IDL declarations and the ES binding in the "(core)" subset.
So revising:
Infra
|
IDL (core)
|
ES6 (core)
|
ES6 (stdlib)
|
IDL (extended)
|
IDL (bindings) <—> HTML
\ /
Web specifications
So revising some more following https://github.com/heycam/webidl/issues/486#issuecomment-349605422:
Infra
|
IDL (core)
|
ES6 (core)
|
IDL (core bindings)
|
ES6 (stdlib)
|
IDL (extended)
|
IDL (extended bindings) <—> HTML
\ /
Web specifications
Note I'm not suggesting we actually split documents up that way. Just that we get a shared understanding of the boundaries.
Why would ES6 (core) depend on IDL (core), as opposed to them being side by side specs with no mutual dependency?
Good point, we're looking at something like this, then, I suppose (visualizing this is actually useful for me, maybe it's a n annoyance to others; if so, apologies):
Infra
/ \
IDL (core) <—> ES6 (core)
/ \ / \
| IDL (core bindings) |
| | /
| ES6 (stdlib)
\ |
IDL (extended) ?
| |
IDL (extended bindings) <—> HTML
\ /
Web specifications
Sounds good, except I think you could get rid of the arrow between IDL (core) and ES6 (core), as well as ES6 (stdlib) to IDL (extended bindings), though you'd want one from IDL (core bindings) to IDL (extended bindings).
And so…
Infra
/ \
IDL (core) ES6 (core)
/ \ / \
| IDL (core bindings) \
| | \ \
| | ES6 (stdlib)
IDL (extended) |
\ |
IDL (extended bindings) <—> HTML
\ /
Web specifications
Edit: a few small fixes.
I theorize that the subset of WebIDL we'd want for 262 is small enough relative to all of WebIDL that the benefits of @littledan's proposed layering will be pretty nice in terms of clarity and understandability. It also serves as a nice way to document the subset of WebIDL in use.
I looked into this, and it seems the opposite is true. At a quick glance, ES would use way more of Web IDL than URL does, especially given the proposals to introduce new features specifically for ES.
Things not needed by ES by my count are:
This enumeration indicates to me that perhaps one resolution that would help people understand how Web IDL is a good base layer below ECMAScript is by more aggressively renaming legacy things to legacy, as we've intended for some time, and possibly moving them to an appendix, if people think that would help. That kind of separation, which is already aligned with Web IDL's goals, feels better than these complex layering diagrams---which don't account for how ES would be a peer to URL and friends, in how they depend on Web IDL.
That kind of separation, which is already aligned with Web IDL's goals, feels better than these complex layering diagrams---which don't account for how ES would be a peer to URL and friends, in how they depend on Web IDL.
Yeah. Can't really show the direct IDL —> ES stdlib link, but bringing the ES stdlib at the bottom helps clarify this:
Infra
/ \
IDL (core) ES6 (core) --------------------
/ \ / \
| IDL (core bindings) -------------- |
| | \ |
| | \ |
IDL (extended) | \ |
\ | \ |
IDL (extended bindings) <—> HTML \ |
\ / \ |
Web specifications ES6 (stdlib)
One thing that @domenic 's comment touches on is that we have different conventions for the WHATWG/W3C and ECMA specs, and it's not clear that we should change either of these conventions (which side would be interested in a change, anyway?). Rather, we can use IDL to document the conventions and encourage maintaining them. WebIDL currently marks some things as "legacy" that go contrary to WHATWG/W3C spec conventions. If we maintain two sets of conventions, for ECMA and WHATWG/W3C, maybe we can mark which places a given feature of WebIDL is appropriate for. We could reference that marking from the ECMAScript spec, and say, "The ECMAScript standard library only cares about the ECMA and neutral parts of WebIDL, and are not referencing the WHATWG/W3C parts". (Some things will be legacy and ECMA-only or WHATWG/W3C-only, or proper in ECMA and legacy in WHATWG/W3C; I guess there's several statuses for features.)
I think it's best if we solve these on a case-by-case basis, since I think you'll find that we want platform objects to conform to what TC39 considers best practice. There might be some exceptions where it's hard to change things around, but I think it's hard to give high-level statements about any of this. Once we've done the work of increasing the coverage of IDL to include what ECMAScript needs it'll be much clearer what a better organization would be.
The WebIDL specification includes some types which are really HTML-specific, such as DOMException. There are other places where HTML is referenced, though these seem to mostly be in examples; I have not gone through and examined them all yet.
If we want WebIDL to be most cleanly usable from the ECMAScript specification, ideally these would be factored out and put into a separate document (perhaps part of the HTML specification). I'm not sure, but maybe WebIDL would need some refactoring to permit certain types or extended attributes to be defined outside of its own document.