thoughts the (re)organization of the specification?

Allen Wirfs-Brock allen at wirfs-brock.com
Fri Nov 2 15:08:47 PDT 2012


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




         



More information about the es-discuss mailing list