Editorial: Update clause range references

[gibson042]

The "Managing Memory" clause inserted by 71c0897 broke some clause range references. We might want a more automated way to catch this, but such restructuring is rare and in the meantime it's just a handful of changes to merge.

[bakkot]

Nice catch.

We might want a more automated way to catch this

Yeah, if you replace clause 6 with clause <emu-xref href="#sec-ecmascript-data-types-and-values"></emu-xref> (or whatever), then the references can't get stale. The emu-xref will turn into a link whose text is the number of the clause (here "6") and whose target is the actual clause.

I think that's probably better than updating the numbers manually. Do you want to do update all the explicit references to clause numbers yourself? I can take care of it otherwise.

[gibson042]

Yeah, if you replace clause 6 with clause <emu-xref href="#sec-ecmascript-data-types-and-values"></emu-xref> (or whatever), then the references can't get stale. The emu-xref will turn into a link whose text is the number of the clause (here "6") and whose target is the actual clause.

References wouldn't get stale, but it'd still be baking in an assumption that the relevant clauses appear in order and fully encompass the standard library (which would be violated if a standard library section is added before The Global Object or after Reflection, or if either of those move). It would be best if there were a single link target, but I understand not wanting to incur the additional depth hit for what is probably the most popular 40% of the spec (or wait for TOC construction changes supporting subsection promotion).

Given the above, do you still want the explicit references?

[bakkot]

It would be best if there were a single link target

I'm not sure what you're suggesting here; can you sketch an example?

Given the above, do you still want the explicit references?

Yeah, I think emu-xrefs are a strict improvement over writing out the numbers explicitly, even though they don't solve all issues.

[jmdyck]

It would be best if there were a single link target

I'm not sure what you're suggesting here; can you sketch an example?

E.g., if you took clauses "The Global Object" through "Reflection" and made them children of a new emu-clause (called, say, "The ECMAScript Standard Library"), then you could xref to that one clause rather than to "clauses 17 through 27".

[jmdyck]

There are also clause-range references in 4.5 Organization of This Specification.

[gibson042]

Thanks for that find, @jmdyck. @bakkot I've replaced the literal clause numbers with <emu-xref>s.

[bakkot]

Thanks much! I'll add a lint rule against for [Cc]lauses? \d at some point so we don't risk having this problem again.

[michaelficarra]

I'd rather list them out instead of using a range. Now we're dependent on the clause ordering. If we list them out, we can re-order clauses all we want without breaking these references.

[bakkot]

@michaelficarra We'd still need to update this sentence because such a reordering would result in these being listed out of order.

More generally, I think readability ought to take precedence over maintainability (especially for things which rarely require maintenance, as here), and I think "as presented in clauses 12 through 15" is more readable than "as presented in clauses 12, 13, 14, and 15", so I would prefer to keep the current PR's wording.

[michaelficarra]

I will reluctantly accept this change since it is easy and doesn't make things worse. For posterity, my preference would be to list out an <emu-xref> for each clause, and when ecmarkup sees that they represent a range, it could render it as we see here. This would address the issues of finding occurrences of the clause ID within the source and including the reference in a clause's reference list. But the other editors don't agree it's worthwhile.