#es-to-dictionary and #dictionary-to-es do not have reader-discernable titles

[equalsJeffH]

..and thus are difficult for readers to easily obtain a link to for use in another spec.

[domenic]

I guess this is a Bikeshed issue where it is not generating self-link anchors for <div algorithm>s. /cc @tabatkins

[tabatkins]

It should have a <dfn> anyway; even if I started auto-genning IDs for algorithm containers and producing self-links, it would still be hard to link, as you'd have to open up WebIDL, click the self-link, copy the URL, then go back to your spec and hand-write an <a href> pointing to it.

[domenic]

The issue here is that Web IDL defines the general concept of "convert an ES value to an IDL value" with a <dfn>, then has a bunch of different algorithms giving specific ways to do that. I'm guessing @equalsJeffH wants to link to the specific algorithm. I guess maybe he should just be linking to https://heycam.github.io/webidl/#dfn-convert-ecmascript-to-idl-value and https://heycam.github.io/webidl/#dfn-convert-idl-to-ecmascript-value however.

[tabatkins]

What's wrong with putting in more specific dfns too?

[equalsJeffH]

@bzbarsky is suggesting that WebAuthn link directly to https://heycam.github.io/webidl/#dictionary-to-es -- which is the most precise thing for us to link to. I am simply noting that one cannot do this today without looking into WebIDL's index.bs source file, or getting the dictionary-to-es identifier from somewhere else.

I note that WebCrypto (which @bzbarsky cited as an example) does not actually link to the #dictionary-to-es algorithm, it says (in various places) only to..

Let ... be the result of converting ... to an ECMAScript Object, as defined by [WebIDL].

..maybe that is sufficient (it seems to essentially be what @domenic is suggesting).

[bzbarsky]

I always feel it's best to link to the most specific thing, instead of just generically linking to "WebIDL" and letting the poor reader try to figure out which part of WebIDL is relevant in this specific case. But maybe that's just me....

I agree that the "easter egg" nature of the #foo-to-es and #es-to-foo anchors in WebIDL is suboptimal. I guess I'm too used to having to view source to find which things are linkable in specs...

[annevk]

I agree with @tabatkins that IDL should just add more <dfn>s. One way to do it might be to add a heading before each type of conversion with dfn export set as attributes.

[tobie]

Right. Planning to add DFNs to each algorithm.

Naming wise, let's do UpperCamelCase so we can then use these as:

let |r| be [=ESToDictionary=](|v|).

The conversion algorithms which convert ES values to specific IDL types could be named ESToDictionary(|v|), those which convert IDL types to values: DictionaryToES(|v|).

So the IDL Dictionary <-> ES value algorithms would be changed to:

<div algorithm>

    An ECMAScript value |V| is [=converted to an IDL value|converted=]
    to an IDL [=dictionary type=] value by
    running the <dfn id="es-to-dictionary" export>ESToDictionary</dfn> algorithm
    (where |D| is the [=dictionary=]):
    […]
</div>
<div algorithm>

    An IDL dictionary value |V| is [=converted to an ECMAScript value|converted=]
    to an ECMAScript <emu-val>Object</emu-val> value by
    running the <dfn id="dictionary-to-es" export>DictionaryToES</dfn> algorithm
    (where |D| is the [=dictionary=]):
    […]
</div>

If there's agreement around the plan + naming, I'll go ahead and submit a PR for these.

[tabatkins]

Use abstract-op on those definitions to preserve the casing (as Anne said in IRC) and you're good.

[domenic]

I am leery of using this particular instance as the gateway to changing from normal English phrases as algorithm names, to ES-style PascalCaseAbstractOps. The web spec space has gotten along great with English phrases until now and I'm not sure how I feel about breaking that tradition so suddenly. But I don't care much so don't let me stop you.