Editorial: use step labels rather than numbers to refer to steps

[bakkot]

This fixes a persistent problem where step numbers would get stale and we'd forget to update them. Now, by given the steps (somewhat arbitrarily chosen) labels, we can refer and link to them explicitly. See tc39/ecmarkup#217 for a description of the syntax.

Marked as draft until a version of ecmarkup with support for the new syntax is published. Edit: done, this should be good to go. Deploy preview looks good to me.

Corresponding ecmarkdown PR at tc39/ecmarkdown#74. Corresponding ecmarkup PR at tc39/ecmarkup#217.

[ljharb]

etc. perhaps a better solution would be to make title automatic when the emu-xref is empty, and also hopefully allowing it to be self-closing (ie <emu-xref />)?

[bakkot]

The presence of the title attribute indicates that the title of the referent rather than its number should be used to provide the text of the reference. As such, title doesn't seem appropriate - steps do not have titles; they can only be referred to by number. Is there a different reason to add it?

and also hopefully allowing it to be self-closing

Ecma262 doesn't currently use any self-closing tags. I'm fine with discussing the possibility of adopting their use, but I would not want to do that in this PR.

[ljharb]

Sure, set that aside; maybe title is the wrong thing, but the contents of the emu-xref should be inferred somehow. Maybe a step attribute?

[bakkot]

the contents of the emu-xref should be inferred somehow

They are; see the screenshot in tc39/ecmarkup#217, which corresponds to this file. That's the default behavior when you leave the tag empty.

[ljharb]

That's not what I see in this PR's build preview - maybe I just got confused because this doesn't include the ecmarkup PR yet?

[bakkot]

Yeah, the build preview won't look right until support for the syntax it relies on is released.

[ljharb]

Would it be better to have an emu-step tag rather than an xref one then?

[brabalan]

Thank you, this will be most useful for JSExplain. It might also solve our need to reference individual algorithms (#1800 and tc39/ecmarkup#172).

[bakkot]

Would it be better to have an emu-step tag rather than an xref one then?

I don't see step references as fundamentally different from any other kind of thing you can emu-xref. What would be the advantage of having a separate tag?

[ljharb]

Other kinds of xrefs can have custom link text which prevents automatically showing the reference's title; i don't see any use case for a link to a step without including a step number.

[bakkot]

That's true; I just made it a warning (to be promoted to a linting error) to include text. It doesn't seem like enough of a difference to warrant a different kind of element, to me.

[ljharb]

With the linting error i guess it's fine, but it seems conceptually like a different element to me. (we probably also want a warning on a non-step xref without title and without text?)

[bakkot]

but it seems conceptually like a different element to me

How so?

we probably also want a warning on a non-step xref without title and without text?

That populates the link text with the clause number / figure number / etc, just as here it is populated with the step number; I don't see any particular problem with it. (We do that in ecma262.)

[ljharb]

I think that "step" is a more specialized subtype of "a link", and i think that merits a different type.

It's not a blocking point, though - it was just an idea :-)

[bakkot]

@ljharb Now that ecmarkup has been bumped the deploy preview renders correctly (see below). If that addresses your concern about title, would you resolve your comments above?

[jmdyck]

Currently, if you're looking at an <emu-xref href="#foo"> in the spec source, and want to go to the referenced point, you can do a search on foo (or, for less noise, id="foo"). This wouldn't work for the <emu-xref> elements introduced by this PR, because the full step-identifiers don't exist in the source. So consider changing the defining syntax from
[label="something"]
to
[id="step-something"]

Similarly, with regard to<emu-alg replaces-step="something">, consider that you might want to allow an emu document (e.g., a proposal) to replace a step in an algorithm in a different spec. For that, a reasonable syntax might be, for example:
<emu-alg replaces-step="https://tc39.es/ecma262/#step-something">
which suggests that the syntax for an in-spec reference should be:
<emu-alg replaces-step="#step-something">

In general, I think you should avoid using not-quite-the-real-identifier in source.

[michaelficarra]

I didn't confirm every single step ID was linked up right, since the tooling should have our backs here.

[syg]

This looks great to me.

+1 on @jmdyck's searchability point. I'd prefer step labels not do any transformation of the label string.

[bakkot]

@jmdyck @syg Updated.