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
Herby
_______________________________________________
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
