It would be really nice if each reference to an algorithm (specifically, runtime semantics) in the spec was specific about which version of the algorithm is being referenced. This would allow generated renderings of the draft on electronic mediums to link to the specific algorithm.
For example, 14.1.18 and 14.2.14 both list sets of steps for different variations of the same algorithm. References to the IteratorBindingInitialization algorithm should be specific about which one is meant. This would make it much easier to read and jump between different sections when necessary.
(From https://github.com/jorendorff/es-spec-html/issues/90#issuecomment-92440636)
(In reply to Caitlin Potter [:caitp] from comment #0)
> It would be really nice if each reference to an algorithm (specifically,
> runtime semantics) in the spec was specific about which version of the
> algorithm is being referenced. This would allow generated renderings of the
> draft on electronic mediums to link to the specific algorithm.
>
> For example, 14.1.18 and 14.2.14 both list sets of steps for different
> variations of the same algorithm. References to the
> IteratorBindingInitialization algorithm should be specific about which one
> is meant. This would make it much easier to read and jump between different
> sections when necessary.
>
> (From
> https://github.com/jorendorff/es-spec-html/issues/90#issuecomment-92440636)
That really doesn't make a lot of sense, at least for the general case. Algorithms with multiple definitions of this sort are intentionally designed to be polymorphically selected based upon the specific entity (usually the grammar rule corresponding to a parse node). Essentially they are doing OO-style dispatch.
Typicality we only use this technique where we have to select from among several possible implementations of the named algorithm. In other words, we do this specifically because we don't know which version of the algorithm will be dynamically applicable at runtime.
Ideally, when reading such algorithms you would like a reference link to take to a list (or a little OO method browser) of all of the possible implementations of the referenced algorithms. The See Also line in such algorithms is an attempt to provide the contents for such a list.
The "See Also" listings don't typically lead to alternative algorithm versions, but to other related algorithms.
Maybe a step could be added to just generate the version-select info separately, I guess. The main pain point in es-spec-html is that there's no hyperlink "at all", which is very painful on mobile Safari, and not so great on a desktop either. Some of these algorithms are referenced many, many times, and it can be quite a lot of digging to find the right one.
But yeah, fine, maybe that's more a problem for es-spec-html
Here's an idea:
Metadata at the header of each version of these "polymorphic" sets of algorithm steps, as a description of the main use of those sets of algorithm steps.
For instance:
IteratorBindingInitialization [[Destructuring]]
IteratorBindingInitialization [[Functions, Generators, Methods]]
IteratorBindingInitialization [[Arrow Functions]]
or something like that
The little annotation would make it easier to generate a list of algorithm versions that would actually help you choose the one you're looking for?
(In reply to Caitlin Potter [:caitp] from comment #2)
> The "See Also" listings don't typically lead to alternative algorithm
> versions, but to other related algorithms.
Nope. All algorithms that are polymorphic over some set of grammar productions begin with a "See Also:" line that cross-references to all of the other sections that contains definitions of that algorithm. For one of many examples see: http://people.mozilla.org/~jorendorff/es6-draft.html#sec-comma-operator-static-semantics-isfunctiondefinition
(In reply to Allen Wirfs-Brock from comment #4)
> (In reply to Caitlin Potter [:caitp] from comment #2)
> > The "See Also" listings don't typically lead to alternative algorithm
> > versions, but to other related algorithms.
>
> Nope. All algorithms that are polymorphic over some set of grammar
> productions begin with a "See Also:" line that cross-references to all of
> the other sections that contains definitions of that algorithm. For one of
> many examples see:
> http://people.mozilla.org/~jorendorff/es6-draft.html#sec-comma-operator-
> static-semantics-isfunctiondefinition
Okay fine, but it's still just a list of numbers which are totally meaningless to human readers and don't really inform a decision about which item you care about, and you still have to hunt down these items to get to the "See also" section anyways. That's easily solved, with a little bit of metadata concisely explaining what each version is used for
(In reply to Caitlin Potter [:caitp] from comment #5)
>
> Okay fine, but it's still just a list of numbers which are totally
> meaningless to human readers and don't really inform a decision about which
> item you care about, and you still have to hunt down these items to get to
> the "See also" section anyways. That's easily solved, with a little bit of
> metadata concisely explaining what each version is used for
There are actually lists of hyper-linked number and I spend a fair amount of time maintaining the metadata for the linking. If you want you can use that metadata in your tools (as Jason does to replicate the hyper-linking in his HTML rendering). For example, you might use them to present a drop down list.
As for which items you care about, you care about all of them because typically they are all possible alternatives.
closing for ES6. It current is written as intended and we can make any major structural change at this point in the ES6 publication process.
Future editions might decide to change cross referencing conventions or add additional metadata.