Editorial: Expand the "Syntax-Directed Operations" section

[jmdyck]

and establish some conventions for referring to Parse Nodes.

---

commit 1:

Move the definition of "source text matched by" to 5.1.4 The Syntactic Grammar, because it isn't specific to SDOs. It can be (and is, barely) used by early error rules and abstract operations too.

---

commit 2:

Split off a subsection for "Implicit Definitions for Chain Productions"

Occasionally, someone points out that the spec is missing some SDO definitions, and we direct them to this paragraph. Having it be a named section may slightly increase the chance that they will see it, and if not, it at least gives us a more specific id to point them to.

---

commit 3:

Split off a subsection for "Invoking Syntax-Directed Operations"

---

commit 4:

Add a paragraph about the dispatching mechanism for SDOs.
(The shape of the Parse Node determines which algorithm is executed.)

Also, capitalize "Parse Node".

---

commit 5:

Create a subsection for "Referring to Parse Nodes"

---

commit 6:

Early error rules use these phrases too.

---

commit 7 etc:

Change node-references to conform to the conventions.

[michaelficarra]

Suggested change

	<p>Syntax-directed operations are invoked with a Parse Node and, optionally, other parameters by using the conventions on steps <emu-xref href="#step-sdo-invocation-example-1"></emu-xref>, <emu-xref href="#step-sdo-invocation-example-2"></emu-xref>, and <emu-xref href="#step-sdo-invocation-example-3"></emu-xref> in the following algorithm:</p>
	<p>Syntax-directed operations are invoked with a subject Parse Node and, optionally, other parameters by using the conventions on steps <emu-xref href="#step-sdo-invocation-example-1"></emu-xref>, <emu-xref href="#step-sdo-invocation-example-2"></emu-xref>, and <emu-xref href="#step-sdo-invocation-example-3"></emu-xref> in the following algorithm:</p>

to align with the use of the phrase "subject Parse Node" below

[jmdyck]

I agree with the intent, but I'm worried that a reader might think that "a subject Parse Node" was a reference to a term defined elsewhere. We could put 'subject' in italics or quotes, to convey that this is its defining occurrence (sort of), but I think it'd be clearer to say something like:

invoked with a Parse Node (referred to below as 'the subject Parse Node')

Also, the sentence was getting a bit complicated, so I broke it into two.

By the way, I'm not sure that "subject" is the best word. In my code, I've also used "focus" and "target".

[michaelficarra]

Suggested change

	<li>If a production has an optional nonterminal (e.g., “|StatementList?|”), the algorithm must check if the corresponding Parse Node is present before using it (e.g., “If the |StatementList| is present, return the VarDeclaredNames of |StatementList|.”)</li>
	<li>If a production has an optional nonterminal (e.g., “|StatementList?|”), the algorithm must check if the corresponding Parse Node is present before using it (e.g., “If |StatementList| is present, return VarDeclaredNames of |StatementList|.”)</li>

The first "the" should be avoided. The second "the" we're really inconsistent about, but I'd prefer to not encourage it with the example.

[jmdyck]

The first "the" should be avoided.

I'm pretty sure that hasn't been established. (If it has, please link.)

I'm inclined to the opposite opinion: eliding "the" before a nonterminal should be avoided.

Alternatively, we could use a scheme of superscripts such as you suggested in issue #1768. The editors might want to decide on that before this PR goes ahead, to avoid churn.

---

The second "the" we're really inconsistent about, but I'd prefer to not encourage it with the example.

Okay, done.

Would you like a PR that removes "the" from before the SDO-name in invocations? There's about 400 occurrences.

[michaelficarra]

I'm pretty sure that hasn't been established. (If it has, please link.)

It hasn't.

Alternatively, we could use a scheme of superscripts such as you suggested in issue #1768. The editors might want to decide on that before this PR goes ahead, to avoid churn.

Nah, even if we eventually went with that eventually, I'd prefer to first do this intermediate step.

Would you like a PR that removes "the" from before the SDO-name in invocations? There's about 400 occurrences.

If you don't mind, yes. That would help us a lot in discussing the change.

[jmdyck]

According to Editorial-Conventions (from PR #3309), invocations of VarDeclaredNames should be preceded by "the", so I should presumably drop the fixup commit that removed it.

[jmdyck]

Done.

[jmdyck]

I've also merged the other 3 fixup commits into other commits.

[michaelficarra]

I'd swap these.

Suggested change

	<p>To refer to the children of the subject Parse Node: In practice, algorithms only reference children that are instances of nonterminals.</p>
	<p>In practice, algorithms only reference children that are instances of nonterminals. To refer to the children of the subject Parse Node:</p>

[michaelficarra]

The way this is written sounds like editorial guidance, which is unnecessary in the spec. The goal here is just to list notation that they may run across. Can you reword to simplify it?

[jmdyck]

It does kind of sound like editorial guidance, but it's really more a description of editorial variations.

I could reword it, but I'm doubtful that would simplify it. I'll think about it.

[jmdyck]

We could simplify the wording of this section by failing to describe some editorial variations. By that token, the ultimate simplification would be to just drop the section.

But if you want to fully describe the ways that SDOs and Early Error rules refer to Parse Nodes, then I don't think this section can be simplified by rewording. Instead, I think the only way to simplify it would be to reduce/eliminate the variation in the rest of the spec.

For example, if you want a single way to refer to the subject Parse Node, we could change all (~125) occurrences of this |Foo| to this Parse Node. (The alternative, of changing the few occurrences of this Parse Node to this |Foo| could be done for the 2 cases where it's associated with explicit productions, by duplicating the rule for each production. However, that doesn't work when this Parse Node is used in the default definition for Contains, AllPrivateIdentifiersValid, and ContainsArguments.)

But changes like that should maybe be deferred to a later PR.

[michaelficarra]

LGTM otherwise. Some nice improvements here.

[jmdyck]

(force-pushed to resolve merge conflicts)

[michaelficarra]

LGTM

[jmdyck]

(force-pushed to resolve merge conflicts)

[michaelficarra]

I would prefer we were consistent: either "the" is always used to refer to the one on the RHS and we never use "the derived", or we always use "the derived" when the nonterminal appears on both sides.

I don't believe we ever currently intentionally refer to the LHS in our algorithm steps, right?

[jmdyck]

I would prefer we were consistent: either "the" is always used to refer to the one on the RHS and we never use "the derived",

If you have production Foo : Foo Bar, and the algorithm refers to "the Foo", I think people who haven't memorized the wording rules might be confused.

or we always use "the derived" when the nonterminal appears on both sides.

I think this PR accomplishes that, but I'd have to check.

I don't believe we ever currently intentionally refer to the LHS in our algorithm steps, right?

Sure we do, lots of times. Search for "this |" in the result of this PR. (You can search for that in the status quo too, but it will miss lots of cases.)

[github-actions]

The rendered spec preview for this PR is available as a single page at https://tc39.es/ecma262/pr/3210 and as multiple pages at https://tc39.es/ecma262/pr/3210/multipage .