thoughts the (re)organization of the specification?
On Fri, Nov 2, 2012 at 11:08 PM, Allen Wirfs-Brock <allen at wirfs-brock.com>wrote:
I'm now looking at the work to implement the refactoring of the internal methods in section 8 and I see we are probably going to loose even more of the section number correspondence with previous editions. This tempts me to seize the moment, abandon the legacy organization, and reorganize in a more logical manner.
carpe diem
Just speaking as a spec reader, I say go for it.
Same here. Carpe diem.
+1
I'm not sure that there would be enough content, but you could have a part titled “Grammar”.
On Nov 2, 2012, at 23:08 , Allen Wirfs-Brock wrote:
I'm now looking at the work to implement the refactoring of the internal methods in section 8 and I see we are probably going to loose even more of the section number correspondence with previous editions. This tempts me to seize the moment, abandon the legacy organization, and reorganize in a more logical manner.
Yes, please.
The ECMAScript Standard Library (15) [potentially some reordering and reorganization]
I'd suggest:
-
Break it up into separate chapters for each of the current second-level sections, plus one for general requirements for all standard built-ins (the currently unnumbered introduction). Given the size of the ES6 spec, we may want to produce a multi-part HTML version and/or an ePub version for tablets, and for both a single chapter containing half the spec would be hard to digest.
-
Reorganize the method lists from sediment layers back into some logical structure.
Norbert
Looks good.
Have you considered to split this spec into two part: one is for language implementer and the other is for language user?
2012/11/3 Allen Wirfs-Brock <allen at wirfs-brock.com>
Have you considered to split this spec into two part: one is for language implementer and the other is for language user?
Interesting idea! You could argue that writing the second part is the job of JavaScript book authors.
It's always fun to think of ways to make a better spec. But also good to keep in mind the risks:
-
The spec is not in any machine-readable form, meaning it's neither testable nor formally verifiable in any way. This means refactoring must be done carefully, since it can't be verified.
-
The more radical the changes, the more risk of introducing bugs, ranging from minor to deep/logical. Even minor bugs risk interoperability problems as implementers diverge in interpretation.
-
Major rejiggering of the spec could result in difficulties in tracking implementation conformance, as implementations are often written to follow the spec structure, and often have inline comments referencing their corresponding ES3/5 semantic steps. But I chatted with Jason Orendorff and he wasn't too concerned about Allen's suggestions.
-
The more radical the changes, the more editorial work it takes. We're on a schedule, we can't fork Allen, and anyway it'd probably be hard to have multiple authors doing serious concurrent work within Word.
That said, Allen's the best judge of what organizational changes he thinks need to be made and what he can reasonably accomplish within our time frame. I love the changes Allen made in ES5 (e.g. the declarative environment frames), and I'm happy to see evolutionary improvements to the structure of the spec.
David Herman wrote:
- The spec is not in any machine-readable form, meaning it's neither testable nor formally verifiable in any way.
I'm working on transforming the spec into a machine-friendly form. (That's how I come up with most of the bugs I submit.) Eventually, it could be testable. I don't think it'll ever be formally verifiable (what would you verify it against?), but it could be analyzed to establish some measure of completeness and consistency.
Le 02/11/2012 23:08, Allen Wirfs-Brock a écrit :
(...)
Here is the new structure that I have in mind, with reference to existing ES5 (section numbers:)
Introductory Material
The ECMAScript Computational Engine
The ECMAScript Programming Language
The ECMAScript Standard Library (15)
Annexes
I have come to an equivalent organisation when thinking about reorganizing MDN JavaScript documentation.
One of the issue is the correspondence between the spec. organization and the test262 organization. We already have massive changes changes and the algorithm and algorithm set level that will impact test232, so I'm not sure that the higher level reorg that I'm thinking about would have that much more impact on it.
I'm not that worried about that aspect. IIRC, there will still be an independent ES5 test suite, so it can follow ES5 chapter numbering, while test262 for ES6 can follow the ES6 spec organisation.
On Nov 3, 2012, at 12:16 AM, Michael Dyck <jmdyck at ibiblio.org> wrote:
David Herman wrote:
- The spec is not in any machine-readable form, meaning it's neither testable nor formally verifiable in any way.
I'm working on transforming the spec into a machine-friendly form. (That's how I come up with most of the bugs I submit.)
Nice!
Do you do this transformation by hand? There have been several research projects that formalized the spec. I'm not saying it can't be done, I'm saying that the normative spec itself is not machine-readable, so you can't easily compare the before/after of a refactoring to check for bugs.
Now, even with hand transformations, if we were to take a formalized version of ES5 and formalized version of ES6 we could conceivably try to check them. But it's just not worth blocking the progress of the spec on these kinds of things. My feeling is, I'm fine with whatever changes Allen thinks are reasonable to make, but it's not worth doing more serious reworking of the spec if it means we either incur higher risk or block progress on formalization and testing/verification work.
Eventually, it could be testable. I don't think it'll ever be formally verifiable (what would you verify it against?),
Verification in the context of a language semantics just means proving properties you want to be true. But specifically, I'm talking about testing or verifying equivalence between the ES5 and ES6 version of things that have been refactored.
David Herman wrote:
On Nov 3, 2012, at 12:16 AM, Michael Dyck <jmdyck at ibiblio.org> wrote:
David Herman wrote:
- The spec is not in any machine-readable form, meaning it's neither testable nor formally verifiable in any way. I'm working on transforming the spec into a machine-friendly form. (That's how I come up with most of the bugs I submit.)
Nice!
Do you do this transformation by hand?
No, it's all scripted, otherwise I'd have to go back to square one each time a new revision came out.
I gave an overview here a year ago: esdiscuss/2011-October/017677 Steps (1) and (2) of the overview are still quite accurate about my current work, but step (3) has changed: rather than executing the spec, I'm focusing more on doing static analysis of it, as that's fairly productive for finding spec-bugs.
There have been several research projects that formalized the spec. I'm not saying it can't be done, I'm saying that the normative spec itself is not machine-readable, so you can't easily compare the before/after of a refactoring to check for bugs.
True, not easily. My whole pipeline from MS Word file to machine-friendly file takes about 20 minutes (the majority of which is just waiting for OpenOffice to load the .doc). In practice, I break the pipeline into several steps, so that my day-to-day work only iterates on the last couple steps, but if you wanted to check for bugs after each refactoring, you'd need to run the whole pipeline. (On top of that, there's the fact that each new revision introduces bugs/variations that are severe enough that they actually cause the pipeline to break, so there's a few hours of tweaking the pipeline to accept the new input.)
It would be nice (and not just for me) if the working version of the spec were in a more 'transformable' format than MS Word, but that seems unlikely: esdiscuss/2011-October/017275
if we were to take a formalized version of ES5 and formalized version of ES6 we could conceivably try to check them. But it's just not worth blocking the progress of the spec on these kinds of things.
Not sure why you think it would block the progress of the spec. It wouldn't have to be AWB that does the checking.
My feeling is, I'm fine with whatever changes Allen thinks are reasonable to make, but it's not worth doing more serious reworking of the spec if it means we either incur higher risk or block progress on formalization and testing/verification work.
I don't see how it could block progress on formalization or testing.
As for verification:
I'm talking about testing or verifying equivalence between the ES5 and ES6 version of things that have been refactored.
Ah. Yes, that'd be tough. Mind you, it'd be tough even without the refactoring. Is anyone working on it?
+1
2012/11/2 Allen Wirfs-Brock <allen at wirfs-brock.com>
I'm now looking at the work to implement the refactoring of the internal methods in section 8 and I see we are probably going to loose even more of the section number correspondence with previous editions. This tempts me to seize the moment, abandon the legacy organization, and reorganize in a more logical manner.
+1
In both ES5 and ES6 (so far) we have generally tried to maintain the section structure of the previous editions. Occasionally we have had to do some minor subsection renumbering (or not so minor in the case of ES5 section 10) but have generally maintained the overall structure of the entire document, even when it has appeared to non-optimial or even confusing.
I'm now looking at the work to implement the refactoring of the internal methods in section 8 and I see we are probably going to loose even more of the section number correspondence with previous editions. This tempts me to seize the moment, abandon the legacy organization, and reorganize in a more logical manner.
Here is the new structure that I have in mind, with reference to existing ES5 (section numbers:)
Introductory Material Scope (1) Conformance (2) Normative References (3) Overview (4) Notational Conventions(5)
The ECMAScript Computational Engine Data Types and Values (8) Commonly used Abstract Operations (9) ECMAScript Execution (10 and possibly parts of 14) [Possibly new material related to module loaders and realms]
The ECMAScript Programming Language Source Text (6) Conformance, Error Handling, and Extensions (16) Lexical Tokens (7) Expressions (11) Statements (12) Functions and Classes (13) Scripts and Modules (14)
The ECMAScript Standard Library (15) [potentially some reordering and reorganization]
Annexes
What thoughts do people have about this? Should we go for an improved document organization or should be continue to patch around the current structure, probably forever. If we do restructure, I would probably do most of the work after we were feature complete and until them, only make incremental changes that make sense that the context of new feature work. But it would be helpful to decide soon which path we are going to take.
One of the issue is the correspondence between the spec. organization and the test262 organization. We already have massive changes changes and the algorithm and algorithm set level that will impact test232, so I'm not sure that the higher level reorg that I'm thinking about would have that much more impact on it.
Feedback???
In both ES5 and ES6 (so far) we have generally tried to maintain the section structure of the previous editions. Occasionally we have had to do some minor subsection renumbering (or not so minor in the case of ES5 section 10) but have generally maintained the overall structure of the entire document, even when it has appeared to non-optimial or even confusing. I'm now looking at the work to implement the refactoring of the internal methods in section 8 and I see we are probably going to loose even more of the section number correspondence with previous editions. This tempts me to seize the moment, abandon the legacy organization, and reorganize in a more logical manner. Here is the new structure that I have in mind, with reference to existing ES5 (section numbers:) Introductory Material Scope (1) Conformance (2) Normative References (3) Overview (4) Notational Conventions(5) The ECMAScript Computational Engine Data Types and Values (8) Commonly used Abstract Operations (9) ECMAScript Execution (10 and possibly parts of 14) [Possibly new material related to module loaders and realms] The ECMAScript Programming Language Source Text (6) Conformance, Error Handling, and Extensions (16) Lexical Tokens (7) Expressions (11) Statements (12) Functions and Classes (13) Scripts and Modules (14) The ECMAScript Standard Library (15) [potentially some reordering and reorganization] Annexes What thoughts do people have about this? Should we go for an improved document organization or should be continue to patch around the current structure, probably forever. If we do restructure, I would probably do most of the work after we were feature complete and until them, only make incremental changes that make sense that the context of new feature work. But it would be helpful to decide soon which path we are going to take. One of the issue is the correspondence between the spec. organization and the test262 organization. We already have massive changes changes and the algorithm and algorithm set level that will impact test232, so I'm not sure that the higher level reorg that I'm thinking about would have that much more impact on it. Feedback??? Allen