Thanks, for the great feedback.
Annex F was my own attempt and keeping track of all the algorithms, but I out
grew it and it's too much trouble to manually keep it up to date while things
are still in flux. The other tension I've run into between easy identification
ia section numbers and a table of contents that's so big it's hard to get
around within a navigation pane.
For now, I'm going to try giving each semantic routine in a subsection, a
section number. Note this may include multiple algorithms corresponding to
various productions. I'll also add a "see also" under each such heading that
references other subsections that implement the same semantic action for other
productions. That should make it easier to navigate to all implementation of,
for example, "BindingInitialisation".
What we have here is a highly polymorphic nonlinear program and as old
Smalltalker knows, the best way to find your way around is at any reference to
a name to be able to popup a navigable list of both implementaors and callers
of that name. Maybe that's something we could get working in the HTML version.
We're already halfway there with some of the definition links.
For now, I need to mostly focus on getting the spec. feature complete by the
end of the year. After that we will have some time where we can cleanup the
presentation.
Still, keep the suggestions coming and feel free to file bugs on such things.
Allen
On Sep 11, 2013, at 3:28 PM, Jason Orendorff wrote:
> On Sep 10, 2013, at 5:38 PM, Oliver Hunt wrote:
>> The current spec layout seems to be a substantial regression in terms of
>> usability vs. the old spec.
>
> Allen, here are a few concrete usability concerns that I think could
> be addressed... it just takes time. :-|
>
> 1. In the ES6 drafts, as opposed to ES5:
>
> * many more algorithms do not have unique names.
>
> * more sections contain a lot of algorithms (for example,
> 14.1.1.2 contains 13 implementations of 5 different methods).
>
> * more algorithms have names that are multiple words, like
> "Binding Initialisation" (with a space between, as opposed to
> "ToString", "GetValue", "CheckObjectCoercible").
>
> These things combined have made it harder for me to talk about the
> spec with others in practice. Just reporting a bug in an algorithm
> requires figuring out how to refer to it.
>
> Our implementation has comments like: `// ES5 8.12.9 Step 1`.
> There is no similarly concise way to refer to some ES6 algorithms.
>
> Proposed fixes:
>
> * Give every algorithm (that is, every list of steps) its own
> section heading and/or its own unique name. There will be a lot. It's
> worth it. Ideally, we'd have a systematic naming scheme
> ("OrdinaryFunction»[[Call]]",
> "FormalParameterList#3»BindingInitialization" since
> FormalParameterList has multiple productions)
>
> These names could live in the document’s margins or something,
> if making them all section headings is just too much.
>
> * Run together all multiword method names ("BindingInitialisation").
>
> 2. There is no way to find, for example, all Binding Initialisation
> implementations. You can search the document. Having found one
> implementation, you can't tell if there are others.
>
> In ES6 many more methods have multiple implementations, and they
> have more implementations on average.
>
> Also it's not clear whether you're looking at all the
> implementations or if there are others, possibly living in distant
> sections. Algorithms are not grouped strictly by name
> ("horizontally"), nor by class/grammar production ("vertically"). It's
> a hybrid approach. I can see why. But it's surprising.
>
> This is a major problem for people trying to read the spec. Right
> now, if a step says "Perform Binding Instantiation for lhs..." there
> is nothing for "Binding Instantiation" to link to.
>
> I propose adding a section for each method that has multiple
> implementations. This new section would (a) have the name of the
> method as its heading, and serve as the link target for all the
> method's call sites; (b) explain informally what the method is—its
> purpose and roughly what you can expect to have happen when you see
> it's being called—and (c) list all algorithms that implement it, with
> links (except Evaluation, which has too many implementations to list).
> The spec currently does this, for some methods, using tables (Table 4
> and Table 5 in 6.1.6.2; and Annex F)—but not all, and the
> implementation lists are out of date. I can see this sort of thing
> being left until later in the ES6 cycle, but it would be awfully
> useful to have (a) and (b) now.
>
> 3. Along similar lines, it would be fantastic if every builtin class
> had something like Table 37 — I don't know if a table is the right
> format, but just a list of the data properties and an informal
> description of what they're for.
>
> "Show me your flow charts and conceal your tables and I shall
> continue to be mystified;" and all that.
>
> 4. Can we rename either PropertyDescriptor.[[Get/Set]] or
> Object.[[Get/Set]]? Maybe PropertyDescriptor.[[GetAccessor]]; or else
> Object.[[GetProperty]].
>
> Not a new issue in ES6. But fixable in ES6.
>
> -j
>
_______________________________________________
es-discuss mailing list
es-discuss@mozilla.org
https://mail.mozilla.org/listinfo/es-discuss
