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.
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)orO.[[InternalMethod]](arg)ends up as a link, which is not desirable.[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:
<a href>. Specs should not have many of these.<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>[(at least, not without escaping).]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-thinginstead ofid-of-thing. We could usebiblioname#id-of-thingfor 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.