Please volunteer to maintain the HTML version of the spec

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Please volunteer to maintain the HTML version of the spec

Jason Orendorff
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
_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Please volunteer to maintain the HTML version of the spec

Michael Dyck
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:
>      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.

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

-Michael
_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Please volunteer to maintain the HTML version of the spec

Jason Orendorff
On Thu, Apr 16, 2015 at 3:35 PM, Michael Dyck <[hidden email]> 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).

-j
_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Please volunteer to maintain the HTML version of the spec

Allen Wirfs-Brock

On Apr 17, 2015, at 6:20 AM, Jason Orendorff wrote:

On Thu, Apr 16, 2015 at 3:35 PM, Michael Dyck <[hidden email]> 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 https://github.com/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 http://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")


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.

Allen


_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Please volunteer to maintain the HTML version of the spec

Axel Rauschmayer
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.

-- 
Dr. Axel Rauschmayer
[hidden email]
rauschma.de




_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss
Reply | Threaded
Open this post in threaded view
|

Re: Please volunteer to maintain the HTML version of the spec

Boris Zbarsky
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.

-Boris
_______________________________________________
es-discuss mailing list
[hidden email]
https://mail.mozilla.org/listinfo/es-discuss