Link syntax

[domenic]

I hear @rwaldron wants a link syntax nicer than <a href>. Let's figure that out.

Directly borrowing CommonMark link syntax has a few problems in my opinion. In order from worst to least-bad, they are:

• [[internalSlot]] (parenthetical note) or O.[[InternalMethod]](arg) ends up as a link, which is not desirable.
• Internal links are common; external links are uncommon. Internal links often want auto-generated text (emu-xref style). Markdown requires text inside the brackets. We should have a syntax that fits with these needs better.
• The whole forward-reference model where you can do [x][y] or [x][] or similar, with [y]: ... or [x]: ... defined "later", is way complicated to implement and gives too many options.

Instead I propose the following:

• For external links, continue using <a href>. Specs should not have many of these.
• For "internal" links (including references to things in the biblios), we have a Markdown-inspired syntax for generating <emu-xref>s. My first pass:
  • [#](id-of-thing) => <emu-xref href="#id-of-thing"></emu-xref>
  • [!](id-of-thing) => <emu-xref href="#id-of-thing" title></emu-xref>
  • [any other characters](id-of-thing) => <emu-xref href="#id-of-thing">any other characters</emu-xref>
  • Except that "any other characters" cannot start with [ (at least, not without escaping).
• No forward references, and I'd say don't allow any spaces between ] and (.

I have no strong feelings on this syntax; [#] and [!] are arbitrary and chosen for brevity, but we could do other things like maybe ##(id-of-thing) and !!(id-of-thing), or choose other characters, or whatever. We could use different syntax that looks a bit less like Markdown so that people don't try to put URLs in the parens. We could use #id-of-thing instead of id-of-thing. We could use biblioname#id-of-thing for external references if we don't want to require unique IDs across referenced specs. Discuss!

Note also that we want tc39/ecmarkup#24 for this to be fully useful.

[jmdyck]

[any other characters](id-of-thing) => <emu-xref href="#id-of-thing">any other characters</emu-xref>

Note that the ES spec has at least one unintended match for that pattern:

F[@@hasInstance](v)

and possibly more, depending on how strict your pattern for id-of-thing is.

[domenic]

Good catch. That points toward maybe using a different syntax? Or just expanding the blacklist.

[bterlson]

I would prefer to expand the blacklist if possible as I put a lot of value in using MD syntax wherever possible. But, since generally conflicts with property-access-then-function-call we might just have a fundamental difference we have to handle with different syntax. For example, if there's ever a case where F[#something]() is a thing we'll be in trouble.

Maybe we should begin bikeshedding alternative syntax?