search

tc39 / proposals

Tracking ECMAScript Proposals
https://tc39.github.io/process-document/
18.13k stars 715 forks source link

Idea: Make merged/landed proposals redirect to corresponding parts of the ES current draft #360

Open sideshowbarker opened 3 years ago

sideshowbarker commented 3 years ago

After a proposal has gone through all the stages and gets merged into the spec, change the body start tag in the HTML source of the proposal to this:

<body onload='(function() { if (location.hash) { location.href = "https://tc39.es/ecma262/" + location.hash; }})()'>

…or better yet — now that there’s a multipage version:

<body onload='(function() { if (location.hash) { location.href = "https://tc39.es/ecma262/multipage/" + location.hash; }})()'>

In other words, make the proposal document redirect to the corresponding fragment of the current ES draft.

That way, any existing links anywhere to the proposal that have fragment parts will get redirected to the corresponding anchors in the current ES draft (while fragment-less links to the proposal itself won’t get redirected).

For example, https://tc39.es/proposal-class-fields/#prod-PrivateIdentifier would redirect to https://tc39.es/ecma262/#prod-PrivateIdentifier — or preferably, to https://tc39.es/ecma262/multipage/ecmascript-language-lexical-grammar.html#prod-PrivateIdentifier.

This would work because y’all seem to have a policy/practice/convention of all id attributes in the proposal source being preserved as-is when you merge them into the ES spec source.

bakkot commented 3 years ago

There's not usually a single fragment of the ES spec to which a given proposal corresponds - most proposals touch parts across many sections.

sideshowbarker commented 3 years ago

There's not usually a single fragment of the ES spec to which a given proposal corresponds - most proposals touch parts across many sections.

Yes, I understand that. What my suggestion would cause is that all the fragment IDs for all parts of the proposal would redirect to the exact same fragment IDs in the current ES draft.

For example, https://tc39.es/proposal-class-fields/#prod-PrivateIdentifier would redirect to https://tc39.es/ecma262/#prod-PrivateIdentifier — or preferably, to https://tc39.es/ecma262/multipage/ecmascript-language-lexical-grammar.html#prod-PrivateIdentifier.

This would work because y’all seem to have a policy/practice/convention of all id attributes in the proposal source being preserved as-is when you merge them into the ES spec source.

(I’ve edited/updated the issue description to include the info from this comment.)

mpcsh commented 3 years ago

personally, I get a lot of value from the diff view on the proposal pages - I wouldn't want to see that go away. for example, if someone links me to the PrivateIdentifier section that you've been using as an example, I really like seeing what additions were made by the proposal. I think it's important to keep that functionality around even after a proposal lands.

ljharb commented 3 years ago

(separately, the single-page, not the multi page, version of the spec is the canonical one and ideally everyone external only links to the single-page version)

bakkot commented 3 years ago

(separately, the single-page, not the multi page, version of the spec is the canonical one and ideally everyone external only links to the single-page version)

It's true that the single-page version is canonical, but I disagree strongly with the claim that this implies everyone ought to link to it. The two documents have the same content, by construction, and the multi-page one is friendlier for many users.

sideshowbarker commented 3 years ago

(separately, the single-page, not the multi page, version of the spec is the canonical one and ideally everyone external only links to the single-page version)

In places such as https://github.com/w3c/browser-specs/blob/master/specs.json#L67 and https://github.com/tobie/specref/blob/main/refs/biblio.json#L1098, we’re now very intentionally referencing the multipage ES spec rather than the single-page.

And for MDN, we’re following a policy of only linking to the multipage version — just as for links to the HTML spec, we have a policy of only linking to the similar multipage version of that.

In the cases of both specs, the primary reason for linking to the multipage versions is better user experience:

I suspect you’d likely not have great success getting third-party sites to avoid linking to the multipage version.

ljharb commented 3 years ago

@sideshowbarker thats not my experience outside of chrome, which has a particularly poor experience for the single-page version.