search

whatwg / webidl

Web IDL Standard
https://webidl.spec.whatwg.org/
Other
400 stars 159 forks source link

Considering factoring WebIDL to allow use from the ECMAScript specification #486

Open littledan opened 6 years ago

littledan commented 6 years ago

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.

domenic commented 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.

littledan commented 6 years ago

OK, what about having a third document, "IDL types for the Web Platform"?

domenic commented 6 years ago

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.

tobie commented 6 years ago

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.

littledan commented 6 years ago

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.

domenic commented 6 years ago

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.

littledan commented 6 years ago

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.

domenic commented 6 years ago

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

bterlson commented 6 years ago

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.

tobie commented 6 years ago

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.

annevk commented 6 years ago

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.

annevk commented 6 years ago

(I do think it's worth exploring though and see if we can get somewhere satisfactory.)

littledan commented 6 years ago

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?

annevk commented 6 years ago

I'd probably go with "Core" and "Extended" or some such, but yeah, that could work.

marcoscaceres commented 6 years ago

Kindly please no. We have enough trouble with the W3C TR “version 1” confusing everyone, and tracking this version also.

tobie commented 6 years ago

@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
marcoscaceres commented 6 years ago

Core and extended could work better - so long as it’s clearly specified as to why the split.

tobie commented 6 years ago

@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…).

littledan commented 6 years ago

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.

tobie commented 6 years ago

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.

littledan commented 6 years ago

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.

tobie commented 6 years ago

Where would the ES binding be? In IDL (extended)?

annevk commented 6 years ago

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.

tobie commented 6 years ago

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?

littledan commented 6 years ago

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.

tobie commented 6 years ago

So revising:

        Infra
          |
         IDL (core)
          |
         ES6 (core)
          |
         ES6 (stdlib)
          |
         IDL (extended)
          |
         IDL (bindings)   <—>  HTML
                      \        /
                   Web specifications
tobie commented 6 years ago

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.

littledan commented 6 years ago

Why would ES6 (core) depend on IDL (core), as opposed to them being side by side specs with no mutual dependency?

tobie commented 6 years ago

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
littledan commented 6 years ago

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

tobie commented 6 years ago

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.

domenic commented 6 years ago

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.

tobie commented 6 years ago

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)
littledan commented 6 years ago

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

annevk commented 6 years ago

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.