Please volunteer to maintain the HTML version of the spec
On 15-04-16 11:23 AM, Jason Orendorff wrote:
[...] I will not be creating the unofficial HTML version of the spec anymore once ES2015 is final.
If you're interested in maintaining the HTML version, let me know! [...]
I'm interested.
[...]
But there is one more job.
Back in 2013, I committed to keeping links to sections working as the document evolves. So if you click on a link in a very old email (<3 esdiscuss.org) and it points to: people.mozilla.org/~jorendorff/es6-draft.html#sec-binary-bitwise-operators-static-semantics-isanonymousfunctiondefinition which has since been merged with some other sections and renamed, some JS in the page redirects you to that section: people.mozilla.org/~jorendorff/es6-draft.html#sec-isanonymousfunctiondefinition
Each time a new revision is published, some manual steps are required to map broken links to the right sections in the new document.
Do you mean that old 'es6-draft.html' URLs should resolve to the corresponding section in the HTML version of the latest ES7+ draft? (In which case, the latter would need to continue to support (remap) all the old section-ids.) I wonder if people would find that surprising.
Or do you mean that 'es6-draft.html' URLs will resolve to the HTML version of ES6-final, but whoever takes on the job for ES7 should make a similar commitment for 'es7-draft' URLs? (That is, ES7 rev1 wouldn't have any section-id baggage, but it'll grow from there.)
On Thu, Apr 16, 2015 at 3:35 PM, Michael Dyck <jmdyck at ibiblio.org> wrote:
I'm interested.
OK, thanks. I'll get back to you next week. Unfortunately I'm not around today.
Each time a new revision is published, some manual steps are required to map broken links to the right sections in the new document.
Do you mean that old 'es6-draft.html' URLs should resolve to the corresponding section in the HTML version of the latest ES7+ draft? (In which case, the latter would need to continue to support (remap) all the old section-ids.) I wonder if people would find that surprising.
I hadn't considered it.
Given the use cases I know about (mostly es-discuss and in implementations' bug-tracking databases), I think it's better to do it the other way, so that ES6-era links continue to point to an ES6 spec.
Starting from scratch will not save a whole lot of work, though. The work required with each revision is mostly figuring out how to redirect section-ids that were newly changed in that revision, not maintaining the old redirects (which is at most some search-and-replace).
On Apr 17, 2015, at 6:20 AM, Jason Orendorff wrote:
On Thu, Apr 16, 2015 at 3:35 PM, Michael Dyck <jmdyck at ibiblio.org> wrote:
I'm interested.
OK, thanks. I'll get back to you next week. Unfortunately I'm not around today.
We should probably start by forking your repository and hosting it on tc39 so it can be maintained as part of the official TC39 tool suite.
The other big thing we need to accomplish in the near future is to have an "official" html version that can be released as www.ecma-international.org/ecma-262/6/index.html (I may be able to get Ecma to change the last node from "6" to "2015") (See for example www.ecma-international.org/ecma-262/5.1 and also see www.ecma-international.org/publications/standards/Ecma-262.htm and www.ecma-international.org/publications/standards/Ecma-262-arch.htm )
Each time a new revision is published, some manual steps are required to map broken links to the right sections in the new document.
Do you mean that old 'es6-draft.html' URLs should resolve to the corresponding section in the HTML version of the latest ES7+ draft? (In which case, the latter would need to continue to support (remap) all the old section-ids.) I wonder if people would find that surprising.
I hadn't considered it.
Given the use cases I know about (mostly es-discuss and in implementations' bug-tracking databases), I think it's better to do it the other way, so that ES6-era links continue to point to an ES6 spec.
I agree, also blog post and old tweets, etc...
Starting from scratch will not save a whole lot of work, though. The work required with each revision is mostly figuring out how to redirect section-ids that were newly changed in that revision, not maintaining the old redirects (which is at most some search-and-replace).
I could probably come up with a way to include permanent ids in section headings as Word invisible fields.
It would be a little more work for spec. editors (and somewhat bug prone: forgetting to include one, forgetting to change the id when copying a heading, etc) but would eliminate the need to maintain an external map.
I could probably come up with a way to include permanent ids in section headings as Word invisible fields.
It would be a little more work for spec. editors (and somewhat bug prone: forgetting to include one, forgetting to change the id when copying a heading, etc) but would eliminate the need to maintain an external map.
That is a great idea! It may make sense to make each top-level section a separate namespace then it’s easier to keep IDs unique and there is graceful degradation. One way of achieving that is by breaking up the HTML spec into one page per top-level section, but that has disadvantages, too.
On 4/17/15 1:16 PM, Axel Rauschmayer wrote:
One way of achieving that is by breaking up the HTML spec into one page per top-level section, but that has disadvantages, too.
Indeed. Like the ability to search in it. As a spec consumer, having specs broken up like this makes them much harder to work with.
I need to free up some time to work on other things, so I will not be creating the unofficial HTML version of the spec anymore once ES2015 is final.
If you're interested in maintaining the HTML version, let me know! If not, I imagine Allen can use Word to generate HTML versions, so it's not like we'll starve.
What's involved?
Doing the conversion is almost a piece of cake: just run the Python script at jorendorff/es-spec-html, using the
instructions in the README. Then publish the generated HTML file on the Web.
But there is one more job.
Back in 2013, I committed to keeping links to sections working as the document evolves. So if you click on a link in a very old email (<3 esdiscuss.org) and it points to: people.mozilla.org/~jorendorff/es6-draft.html#sec-binary-bitwise-operators-static-semantics-isanonymousfunctiondefinition which has since been merged with some other sections and renamed, some JS in the page redirects you to that section: people.mozilla.org/~jorendorff/es6-draft.html#sec-isanonymousfunctiondefinition
Each time a new revision is published, some manual steps are required to map broken links to the right sections in the new document. It can't be fully automated, though undoubtedly you could improve on what I've been doing. Details on request.
I need to free up some time to work on other things, so I will not be creating the unofficial HTML version of the spec anymore once ES2015 is final. If you're interested in maintaining the HTML version, let me know! If not, I imagine Allen can use Word to generate HTML versions, so it's not like we'll starve. ### What's involved? Doing the conversion is *almost* a piece of cake: just run the Python script at <https://github.com/jorendorff/es-spec-html/>, using the instructions in the README. Then publish the generated HTML file on the Web. But there is one more job. Back in 2013, I committed to keeping links to sections working as the document evolves. So if you click on a link in a very old email (<3 esdiscuss.org) and it points to: https://people.mozilla.org/~jorendorff/es6-draft.html#sec-binary-bitwise-operators-static-semantics-isanonymousfunctiondefinition which has since been merged with some other sections and renamed, some JS in the page redirects you to that section: https://people.mozilla.org/~jorendorff/es6-draft.html#sec-isanonymousfunctiondefinition Each time a new revision is published, some manual steps are required to map broken links to the right sections in the new document. It can't be fully automated, though undoubtedly you could improve on what I've been doing. Details on request. Cheers, -j