Spec feedback on rev 6
Thanks, Peter. This makes me realize that I probably need to write a short guide to reading and reviewing drafts of the specifications. As a first approximation I'll address some of your issues here and then probably reuse some of this material in putting together such a guide.
The best way to report problems with ES6 drafts is to file bugs at bugs.ecmascript.org. Use the product "Draft of the 6th Edition" , the version you are reading, and an appropriate "component" (editorial issues, technical issues, etc.). This is particularly useful for specific bugs such as misspellings or errors in algorithms.
All draft, at least through most of this calendar year, are snapshots taken of my working drafts at fairly arbitrary points in time. They are still far from being complete, often have incomplete treatment of new features, and sometimes are captured in the middle of some major refactoring. It is reasonable to assume that I am aware of the major inconsistencies or missing material, but you can't over report. So if you see something that you think is important to capture, file a bug. For example, the new conventions for dealing with completion values (this is actually something different from we refer to as "completion reform" on the wiki) is largely done but I still need to do a comprehensive review to make sure I've gotten everything that needs to be modified. If you saw places where you think I missed something in that regard, please file a bug.
Some of you issues are questions regarding ES6 design decisions, such as the \u{} escape and the automatic UTF-16 encoding of Unicode supplementary characters. If you want to discuss why these decisions were made or want to argue for an alternative then you should post messages about specific issues to es-discuss. Most of TC39 reads this list, while I'm the main person reading and responding to bug reports. So, if you want wider discussion, use es-discuss.
Grammar anomalies you see are either issues that derive from ES's contextual dependencies between lexing and parsing or from the committee desire to have a generally LR(1) grammar. In some cases, we can only accomplish the latter by using a overly permissive cover grammar and then reparsing with a more restrictive contextually determined grammar. If you have a better way to handle such situations, feel free to start an es-discuss thread.
Similarly, with the use of static semantic (and, for that matter, runtime semantic rules). As the language grows, it has a richer set of semantics that we have to describe. If you have techniques that are both better and practical for an incremental rewrite I'd be happy to discuss them on es-discuss. I'm also experimenting with other ways to deal the the complexity such as the static semantic cross reference in annex F and various forms of indices and internal hyper-links.
Regarding, the target audience. I consider the primary audience to be implementors who must create highly interoperable ES implementations. In one sense, it is all about the edge cases that implementors must get exactly right in order to be completely interoperable. Next comes the authors of interoperability and conformance test suites, such as test262. They need to write tests that help implementor conform to the specification. For third in priority, I would place sophisticated authors and educator. These are the people who will teach the language to the world, and like implementors, they need to know (or at least lookup) edge case behavior. This is not a document for everyday ES codes (although some will use it). It is also not a tutorial on either language design in general, language theory, or the design process behind its creation. The spec. also isn't particularly targeted towards academics. We certainly want to have a sound language and where necessary TC39 members may even prove characteristics of certain features. But such material is not necessarily included in the specification. We don't bias our specification technique specifically towards the preferences of academics. If I had to make a choice between usability (of the spec.) for implementors and usability for academics I would make the choice that favored implementors.
We generally try to minimize tutorial material (eg examples) and redundancy between normative prose descriptions and normative algorithms. Redundant descriptions has historically resulted in internal inconsistencies. We have also seen cases where implementors follow incomplete prose descriptions without referring to the more complete algorithm. For these reasons, I have been converting much of the redundant prose from previous editions into non-normative notes. In general, examples are only used if they seem necessary to clarify some difficult to understand normative point. Sometimes I will insert an example in order to make it clear that some unusual design point is intentional and not a bug in the specification. The spec. generally does not discuss what a feature is good for or how to use it. Having said all that, the spec. doesn't always follow these guidelines. We working on the 6th edition of a fifteen year old document and sometimes older material doesn't follow newer conventions. Cleaning this up is mostly a "if time is available" task.
We generally don't include non-normative rationale material. It would be great for somebody to create a document explaining all of the design rationales for the language. But I don't have the time to do both that and to also produce the actual specification. Rationale material can be minded from es-discuss threads, on wiki.ecmascript.org, and in TC39 minutes. I'd love to see somebody tackle this, but I'm not holding my breadth.
I hope this answers most of you general questions. Thanks for reading and filing bugs. There will be many more drafts so keep reading. I will continue to post version-to-version change markup.
Allen Wirfs-Brock wrote:
We generally try to minimize tutorial material (eg examples) and redundancy between normative prose descriptions and normative algorithms. Redundant descriptions has historically resulted in internal inconsistencies. We have also seen cases where implementors follow incomplete prose descriptions without referring to the more complete algorithm. For these reasons, I have been converting much of the redundant prose from previous editions into non-normative notes. In general, examples are only used if they seem necessary to clarify some difficult to understand normative point. Sometimes I will insert an example in order to make it clear that some unusual design point is intentional and not a bug in the specification. The spec. generally does not discuss what a feature is good for or how to use it. Having said all that, the spec. doesn't always follow these guidelines. We working on the 6th edition of a fifteen year old document and sometimes older material doesn't follow newer conventions. Cleaning this up is mostly a "if time is available" task.
An idea related to this: ECMA-262 spec has a test suite. It could be beneficial from coder PoV (maybe for other readers, especially reading it for the first time / after long pause, too) to include shortened (table-like, inputs plus desired output) test-cases before the actual algorithm. Though the algorithm would still be authoritative.
Herby Vojčík wrote:
Allen Wirfs-Brock wrote:
We generally try to minimize tutorial material (eg examples) and redundancy between normative prose descriptions and normative algorithms. Redundant descriptions has historically resulted in internal inconsistencies. We have also seen cases where implementors follow incomplete prose descriptions without referring to the more complete algorithm. For these reasons, I have been converting much of the redundant prose from previous editions into non-normative notes. In general, examples are only used if they seem necessary to clarify some difficult to understand normative point. Sometimes I will insert an example in order to make it clear that some unusual design point is intentional and not a bug in the specification. The spec. generally does not discuss what a feature is good for or how to use it. Having said all that, the spec. doesn't always follow these guidelines. We working on the 6th edition of a fifteen year old document and sometimes older material doesn't follow newer conventions. Cleaning this up is mostly a "if time is available" task.
An idea related to this: ECMA-262 spec has a test suite. It could be beneficial from coder PoV (maybe for other readers, especially reading it for the first time / after long pause, too) to include shortened (table-like, inputs plus desired output) test-cases before the actual algorithm. Though the algorithm would still be authoritative.
More to go wrong, in my experience -- more spec-bug habitat and potential confusion between informative and normative. This happened especially with ECMA-357 (E4X), which had more prose and motivating examples before the normative spec, where the informative stuff was often wrong or misleading.
Specs need illumination by companion docs, hyperlinking/transcluding codexes, etc. Another reason for HTML spec format (thanks again to jorendorff!).
On Wed, Aug 1, 2012 at 8:11 AM, Brendan Eich <brendan at mozilla.org> wrote:
Specs need illumination by companion docs, hyperlinking/transcluding codexes, etc. Another reason for HTML spec format (thanks again to jorendorff!).
Since test262 is organized according to the spec's section structure, it would be great to have links in both directions between the test262 test case groups and the corresponding section of the online reference.
Brendan Eich wrote:
Herby Vojčík wrote:
Allen Wirfs-Brock wrote:
We generally try to minimize tutorial material (eg examples) and redundancy between normative prose descriptions and normative algorithms. Redundant descriptions has historically resulted in internal inconsistencies. We have also seen cases where implementors follow incomplete prose descriptions without referring to the more complete algorithm. For these reasons, I have been converting much of the redundant prose from previous editions into non-normative notes. In general, examples are only used if they seem necessary to clarify some difficult to understand normative point. Sometimes I will insert an example in order to make it clear that some unusual design point is intentional and not a bug in the specification. The spec. generally does not discuss what a feature is good for or how to use it. Having said all that, the spec. doesn't always follow these guidelines. We working on the 6th edition of a fifteen year old document and sometimes older material doesn't follow newer conventions. Cleaning this up is mostly a "if time is available" task.
An idea related to this: ECMA-262 spec has a test suite. It could be beneficial from coder PoV (maybe for other readers, especially reading it for the first time / after long pause, too) to include shortened (table-like, inputs plus desired output) test-cases before the actual algorithm. Though the algorithm would still be authoritative.
More to go wrong, in my experience -- more spec-bug habitat and potential confusion between informative and normative. This happened especially with ECMA-357 (E4X), which had more prose and motivating examples before the normative spec, where the informative stuff was often wrong or misleading.
Online it is fine to have hyperlinks, but I was thinking more of offline, printed version (I did print ECMA-262 and used it in paper form).
I was not encouraging "informative stuff", I was explicitly speaking about test cases, as there are half-way between - they are test cases for the normative part. I was speaking about test cases exactly so that it will not happen that "informative stuff was often wrong or misleading". After all, looking over test cases is one of the possibilities to see how a piece of code can/should be used.
Maybe, since it's test cases, this could be automated and there could be test-annotated as well as test-free versions of the spec...
Herby Vojčík wrote:
I was not encouraging "informative stuff", I was explicitly speaking about test cases, as there are half-way between - they are test cases for the normative part.
Tests are informative, not normative. This is a matter of definition and there's no middle ground.
In practice, real tests are software, as buggy or buggier than a well-reviewed spec, and less informative than a well-written spec. The spec is normative, though -- never perfect, just the thing people try to rally around first, the repository that's idealized as "upstream" of implementations, testsuites, books, etc.
I've read pretty thoroughly through rev 6 of the spec (offline, with a pen and a printed spec) and seem to have written down at least something on pretty much every page.
It'll take me some time to put it all together digitally, but here are some high level comments (in no particular order):
I'm sure there's one or two more. So I've got two questions before I start digitization of my notes...
1: For what kind of audience does the TC39/ECMA target this spec? To name a few:
2: How would you like me to do this? I can write a single email to this list for every (bigger) issue I found, but I don't want to spam the list. A single email will make individual points get lost in messy comments very fast though. I could add every point to a github-gist for people to comment on, but that would require a github account for people to comment there (not sure how big of an issue this is). I could go through the list with somebody to filter out the smaller points, through irc or skype? Could make typo-part quicker to do. Please let me know :)
Learned a few new things while reading the spec (including some things I think I actually missed/forgot while reading the es5 spec a few years ago), so it's not been in vain regardless :)
Hi, I've read pretty thoroughly through rev 6 of the spec (offline, with a pen and a printed spec) and seem to have written down at least something on pretty much every page. It'll take me some time to put it all together digitally, but here are some high level comments (in no particular order): - String as code point values is not consistently propagated yet - Would suggest to go a step beyond the code point value and leave out unicode where not absolutely required (will explain in followup mail) - The double point unicode characters (and the \u{x*} extension) smell a lot like the "mb_" mess php left when moving to utf (not sure whether this could be solved easily though) - Completion reform has the same problem of inconsistently being propagated in "old" parts of the spec, i dont think all return values are properly handled yet - typeof null still object (personal disappointment :) - Make undefined, NaN, and Infinity a literal (I don't see what issues that might cause, please tell me if any); they're locked down anyways - Many inconsistencies (different ways of doing the same thing in algorithms, explaining things, and even the grammar) - Quite a bit of duplication that could be prevented - The term "exotic" does not seem fitting to this spec, but even if that bikeshed is not reverted; "host" and "native" have still _many_ occurrences - Likewise for "character" (also inconsistently replaced with one of "code point", "code point value", "element", and "code unit") - Missing some of the interesting parts I was looking forward to reading specced (WeakMaps, Proxies, etc) - I think many of the built-in functions and methods could do with a short description (more than "<func>, when called, does this algo:") - Many, many of the algorithms, notes, and rules could do with one or more examples and the rationale behind them. - The new way of doing "static semantics" are really annoying to read (especially offline) when split up like this - When referring to certain abstract (-like) functions, like static semantics, it's really hard to detect this while reading (example: contains), style issue - Large chunk of the parsing theory seems to be irrelevant (spec would be useful even without it) - The new additions seem to take a few shortcuts wrt the grammar. Especially "re-parsing" rules look a bit weird over just one grammar - Making new parts of the spec (modules, using let, using const, etc) "auto strict mode" is really disappointing and will confuse users, new and experienced I'm sure there's one or two more. So I've got two questions before I start digitization of my notes... 1: For what kind of audience does the TC39/ECMA target this spec? To name a few: - Academics (proofs, formalization, background theory) - Implementors (edge casing, exact algorithms, no need for formal proof or background theory) - Advanced coders wanting to jump to the next level (how does it work, rationales, examples) - Coders wanting to learn (ok, probably not) I think it's either 1, 2, or both. But while reading the spec I could not really get a good feeling and it seems to be a mix between the first, second, and maybe even the third type. An answer to this question helps me to determine which items I might ignore :) 2: How would you like me to do this? I can write a single email to this list for every (bigger) issue I found, but I don't want to spam the list. A single email will make individual points get lost in messy comments very fast though. I could add every point to a github-gist for people to comment on, but that would require a github account for people to comment there (not sure how big of an issue this is). I could go through the list with somebody to filter out the smaller points, through irc or skype? Could make typo-part quicker to do. Please let me know :) Learned a few new things while reading the spec (including some things I think I actually missed/forgot while reading the es5 spec a few years ago), so it's not been in vain regardless :) Cheers, - peter