Editorial: consolidate each SDO's definition

[bakkot]

Fixes #1950. Fixes #2251.

This ensures every SDO is defined in a single place (modulo tweaks in Annex B, and excepting Early Errors and Evaluation). That way usages of SDOs can be automatically linked to their definition site, as is done for other abstract operations. This makes the spec much easier to navigate, I think.

That was generally just a matter of moving things around and some minor tweaking or renaming. Most SDOs had a natural place to live: ExportEntries can go in the Exports section, say. We introduced a new top-level "Syntax-Directed Operations" clause to hold some more broadly applicable operations.

However, in a few cases @michaelficarra and I judged that the result would have separated sections which logically ought to be grouped, which we resolved by introducing new SDOs. For example, InstantiateFunctionObject has the semantics for setting up all four kinds of function declaration, and we wanted each those semantics to be together with their respective declaration kind. So we introduced InstantiateOrdinaryFunctionObject, InstantiateGeneratorFunctionObject, InstantiateAsyncGeneratorFunctionObject, and InstantiateAsyncFunctionObject, and made the original InstantiateFunctionObject dispatch the appropriate one.

This is marked as a draft because there's still a few cases to do (specifically IsIdentifierRef, NamedEvaluation, and StringValue), as well as some necessary cleanup (for example, the while statement clause is now entirely empty). Edit: ready to go! Needs tc39/ecmarkup#285 upstreamed, though.

This does not yet allow you to trivially answer the question "what SDOs are defined over this production?", which will come as part of tc39/ecmarkup#276.

Commits should be individually reviewable.

[ljharb]

We went through this on the editor call, and it seems like a great improvement.

[syg]

This is great.

Per the editor call I skipped/skimmed most of the "consolidate" commits as they were script-generated.

[syg]

We're inconsistent between using => and =>. Are there any =>s left after this PR?

[michaelficarra]

I think we should always write > as > when not part of an HTML tag.

[bakkot]

Are there any =>s left after this PR?

One, in OtherPunctuator, which uses > consistently for all punctuators.

I think we should always write > as > when not part of an HTML tag.

Strong disagree. It's less readable for no benefit.

[syg]

Agree with @bakkot on not using >. I prefer =>.

[syg]

As a followup, the new SDO clauses could use more prose in addition to the clause names briefly saying what SDOs are, what each clause is grouping by at a high-level. See existing prose in the Abstract Operations section, for example.

[jmdyck]

I notice that you put type="sdo" only on 'single-clause' SDOs. Wouldn't it also make sense on the remaining multi-clause SDOs?

Or is the 'type' attribute deemed to be an attribute of the aoid, not of the clause?

[jmdyck]

Generally, when a clause defines an aoid, the id attribute is just "sec-" + lowercase(aoid).

(This is just the first occurrence of many.)

[bakkot]

I'm OK with this particular inconsistency, I think.

[jmdyck]

Insert blank line before <emu-clause>?

[bakkot]

I'll make a lint rule for this and address in a followup.

[jmdyck]

Okay.

[jmdyck]

Oh, I forgot one: this PR moves up the defining productions for parameter-related nonterminals, so it should probably move the corresponding emu-prodrefs in Annex A.

[bakkot]

Ah, nice catch. Done.

[bakkot]

Wouldn't it also make sense on the remaining multi-clause SDOs?

Copying from IRC for posterity: the remaining such SDOs are Early Errors, Evaluation, MV, TV, TRV, and the evaluation semantics for RegExp patterns. I and ecmarkup are treating these as being unlike normal SDOs for one reason or another, so I'm not adding the type= attribute to them.

resolved