The "ES6" specification has more complicated language constructs that require
more verbose specification language for many constructs. One of the techniques
I'm using is to have more semantic functions over grammar productions . The
readability of the specification seems to be quite sensitive to how such
functions are organized within the various sections of the specifications. I'm
personally finding it harder to find things in the current draft.
To fix this I've been experimenting with several different organizations and I
would like some feedback on the alternative I've come up with.
The experiments are shown in
http://wiki.ecmascript.org/lib/exe/fetch.php?id=harmony%3Aspecification_drafts&cache=cache&media=harmony:11.1.5-alternatives.pdf
This contains four versions of section 11.5.1 (Object literals). Each section
is about 4 pages long and contains the same specification text, but organized
in slightly different ways.
The first version is what is currently in the specification. All the semantics
definitions are lumped together in a single "Semantics" section in roughly the
same order as the productions occur in the grammar. Each definition includes
the grammar production it applies to so the order doesn't have any semantic
significance.
The second version regroups the semantic functions according to semantic
function. First there are all the static semantic definitions for all the
productions. Then all the PropertyDefinitionList function definitions for the
productions that define it, and so until finally there are the evaluation
function definitions for all the productions.
The third version is ordered just like the second version but it uses explicit
subsection headings for each function group in order to make them more visible.
The four version orders everything by grammar production. It shows a
production and immediately has all the functions that apply to that production.
Take a look at and compare each alternative presentation. Which do you find
more readable? Which makes it easier to find definitions you might be
searching for.
Which style do you think I should use in the specification?
Allen
_______________________________________________
es-discuss mailing list
es-discuss@mozilla.org
https://mail.mozilla.org/listinfo/es-discuss
