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