Spec feedback on rev 6

Herby Vojčík herby at mailbox.sk
Thu Aug 2 01:07:49 PDT 2012

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

> Specs need illumination by companion docs, hyperlinking/transcluding
> codexes, etc. Another reason for HTML spec format (thanks again to
> jorendorff!).
> /be


More information about the es-discuss mailing list