Bikeshed: Multiple possible 'environment' dfn refs.

[hober]

I've got a Bikeshed document that attempts to use the term environment. I've got spec:html; type:dfn; for:/; text:environment in my link-defaults section. Bikeshed emits this warning (emphasis mine):

The following refs show up multiple times in their spec, in a way that Bikeshed can't distinguish between. Either create a manual link, or ask the spec maintainer to add disambiguating attributes (usually a for='' attribute to all of them).
spec:html; type:dfn; for:/; text:environment
https://html.spec.whatwg.org/multipage/infrastructure.html#blob-url-entry-environment
https://html.spec.whatwg.org/multipage/semantics.html#link-options-environment
https://html.spec.whatwg.org/multipage/webappapis.html#environment

Could these definitions be tweaked so Bikeshed can figure out the right one to use? Thanks!

[domenic]

Only one of these is exported, so Bikeshed should only be picking up that one... you shouldn't need a link-defaults block at all.

Maybe this is related to the Shepherd definition scraper continuing to scrape non-exported parts of HTML despite us asking them not to?

[annevk]

Fetch uses <a for=/>environment</a> and that works without warning. I don't really know how link-defaults works. Intuitively I'd say that what you have ought to do the trick, but maybe you're running into https://tabatkins.github.io/bikeshed/#ambi-for? (I tend to avoid link-defaults and the like, instead "hardcoding" it for every reference.)

[hober]

Yeah, switching it to <a for=/>environment</a> and removing the link-defaults entry does the trick. Thanks! Sorry for the noise!

[tabatkins]

Maybe this is related to the Shepherd definition scraper continuing to scrape non-exported parts of HTML despite us asking them not to?

No, it's completely unrelated. You can see with bikeshed refs --type=dfn --text=environment --spec=html that there are indeed 3, with 2 of them unexported.

The issue is that link-defaults causes matching dfns to be treated as exported for your spec's purposes (because you're explicitly asking for them!), the same as explicitly specifying the spec in an autolink. However, those three definitions are indistinguishable, so all three of them match the link-defaults entry and all get flipped on. They should all be fixed.

The first dfn @hober listed shouldn't be exposed as a definition to Bikeshed at all. You can specify this by giving it an empty linking text, with a data-lt="" attribute. (All the dfns in this "external dfns" section should be doing this.)

The second dfn is missing its for value; there should be a data-dfn-for="link processing options" on the dl to scope all the definitions there. All of these also probably do want to be exported, since other specs will need to reference them when defining their "process a link header" algos for their own link types.

The third is marked up correctly.

[domenic]

The first dfn @hober listed shouldn't be exposed as a definition to Bikeshed at all

The second dfn is missing its for value

Our assumption is that since we did not add data-export="" to these, it shouldn't matter how they are marked up.

other specs will need to reference them when defining their "process a link header" algos for their own link types.

HTML is the only spec which can define link types.

[tabatkins]

Our assumption is that since we did not add data-export="" to these, it shouldn't matter how they are marked up.

That's not correct. They're still linkable definitions, keeping them unexported just makes them less immediately visible, to reduce accidental collisions. There are still ways for other specs to link to them, such as what happened in this thread. To actually tell Bikeshed that a definition should not be picked up at all (which is the case for every definition in this section, since none of them are being defined by HTML, but rather are using dfn for Wattsi-internal linking purposes), data-lt="" is the correct markup.

HTML is the only spec which can define link types.

Okay. It should still either be marked up appropriately in the Bikeshed data model so it can be distinguished from the other definition, or marked for Bikeshed to ignore it completely so nobody can reference it at all.

[domenic]

So the idea is we just can't use the <dfn> tag at all, without adding Bikeshed-specific markup to our usage of <dfn> to tell Bikeshed to ignore it? That's unfortunate. I don't see us doing that.

[tabatkins]

...yes? I have to be able to tell dfns meant for Bikeshed to know about from ones that it shouldn't know about, and I can do so either by annotating every dfn that Bikeshed should know or by annotating every one it shouldn't know. The vast majority of specs want 100% of their definitions to be picked up by Bikeshed, and for the minority of exceptions, they still want the vast majority of their definitions to be. (HTML falls into this latter category - it has a small % of exceptions that it uses for its own tooling because Wattsi lacks the ability to autolink to external documents, but all the rest of its dfns should be picked up.) So it makes much more sense for the rare spec to annotate its rare dfn when that case occurs.

I'm not sure where this resistance is coming from. I can write the PR for you, if for some reason it's just a matter of not wanting to spend a few minutes on the task. If it's some more principled rejection of the entire idea, I'd love to understand your reasoning more.

[domenic]

HTML has a lot of definitions Bikeshed should not know about. All of them, by default. We explicitly mark up the ones we want people to use externally, by using data-export or data-dfn-type or other parts of the Bikeshed contract.

We'd prefer if we were able to use the standard dfn element without it being a sign that Bikeshed should index. We will use Bikeshed's data- attributes, when we want Bikeshed's involvement.