Need a way to create xrefs to specs without exporting

[jnurthen]

Is your feature request related to a problem? Please describe.
The following bug was logged against ARIA - w3c/aria#1509
We have references within the ARIA suite where we previously copied all of the definitions into each spec so we didn't need to use xrefs. We changed this in response to w3c/accname#84 but now it seems we are exporting more than we should be. However many of the "common" terms referenced in w3c/aria#1509 are used referenced in multiple ARIA specifications.

Describe the solution you'd like
Provide a way to list specifications to search for definitions without exporting these definitions to the whole world.

Describe alternatives you've considered
We could revert all of this and then we would be back in the initial state.

Can you or your organization fund the work or help with development?
Not at this time

Additional context
Add any other context or screenshots about the feature request here.

[tabatkins]

In Bikeshed, this could be solved by marking the definitions as not exported, then in the specific set of ARIA specs (or more likely, in their boilerplates), adding a <pre class=link-defaults> that specifies the ARIA definition as preferred. This would allow the ARIA specs to reference their version of several common web-platform terms without polluting the global namespace and requiring every single other spec in the ecosystem to disambiguate themselves.

I'm not sure if a similar functionality exists in ReSpec.

[sidvishnoi]

If the definitions are not to be made available to other specs, they should not be marked as exported (or at least be scoped somehow). ReSpec is able to disambiguate this as it only searches in mentioned specs (viz. respecConfig.xref.specs) and ARIA specs are usually more xref'ed among each other than between other specs.

Similar to Bikeshed's link-defaults, ReSpec makes use of data-cite attribute on <a> elements. In this case, ARIA would not export such dfns, and other specs can reference them as:

<a data-cite="aria#dfn-accessibility-api">Accessibility API</a>

<!-- If a term might be referenced multiple times: -->
<dfn data-cite="aria#dfn-accessibility-api">Accessibility API</dfn>  <!-- dfn with data-cite won't be exported -->
<!-- and then: -->
<a>Accessibility API</a>, again <a>Accessibility API</a>

Unfortunately, this would mean sacrificing the benefits of xref. But it's better than polluting global namespace.

It might be useful be add a notion of "protected namespaces", where tools such as Webref would add an additional "namespace" to each dfn (say marked by data-export="namespace"), and Bikeshed/ReSpec won't search/match such definitions unless namespaces are provided as a config option (say xref.namespaces = ["namespace1", "namespace2"]).

On another note, it would be nice if Bikeshed could require a config (say, Specs: spec1 spec2) similar to ReSpec's xref.specs , but that might be too big of breaking change.

[marcoscaceres]

@tabatkins, all definitions are namespaces to the spec that defines them (i.e., Aria's DOMString is not WebIDL's DOMString... as wrong as that is).

Having said that, the ARIA spec is doing the wrong thing by redefining definitions it doesn't own. We should remove the duplicate definitions from ARIA (e.g. DOMString etc) and only export things in one spec.

If the aria specs still want duplicate definitions, then data-noexport is appropriate.

[marcoscaceres]

(Keeping this open, but this is not a ReSpec issue - it's mostly confusion about how the citation ecosystem works ... this is a bug for us tool creators to help people better understand the ecosystem that we've built - I hope to do something for TPAC speced/speced-cg#24 )

[jnurthen]

@sidvishnoi I really don't understand how this would work. If not exported how would the Core-aam spec reference the Accessibility API reference in a maintainable way? We can't reference an internally generated idref in each of the child specifications as maintaining that would be a nightmare.

[sidvishnoi]

@jnurthen Yes, that would be unmaintainable indeed (that's why we added xref in first place). https://github.com/w3c/respec/issues/3687#issuecomment-878861826 is the way forward.

As a last resort, common re-definitions can probably use a data-include="https://w3c.github.io/aria/common-dfns.html" to ease maintenance. This file would have <dfn data-noexport>some term</dfn> for each dfn. Then each spec that data-includes this file could reference these terms as regular links <a>some term</a>. This should be done only if absolutely needed.

[jnurthen]

@sidvishnoi I still don't understand what you are recommending in that comment. For example in CoreAAM I have at least 9 references to <a>Accessibility APIs</a> - how would that work in that specification in order to reference the definition of Accessibility APIs in the ARIA spec?

[jnurthen]

@sidvishnoi We used to have a common terms.html file which we were referencing in all the specs but we were advised by respec to stop doing that so we did.
If we are to go back to that solution we will need respec support to allow us to remove references which are unused in specific specifications which we used to have but broke with https://github.com/w3c/respec/issues/2848. Now we are not on the common profile we no longer have access to that.

[marcoscaceres]

@sidvishnoi, no need to do anything special for the Aria specs... we just need to follow standard practice as we do with any other spec.

The Aria specs have a much right to define and export whatever they want/need as any other spec. I'll work with @jnurthen and get it sorted.

@tabatkins, we should work with the Reffy folks (@dontcallmedom, @tidoust) to see if we can check for definition collisions - and maybe clean things up before we accept specs into the "Browser Specs" listing + WebRef database.

Alternatively, BikeShed probably shouldn't assume the global namespace won't have collisions (it doesn't scale). ReSpec's citation system was designed to deal with this by defining "profiles", e.g., the "web-platform" profile only pulls definitions from "HTML", "INFRA", "URL", "WEBIDL", "DOM", "FETCH", which a spec editor then amends by adding more citations.

A typical setup looks like this:

<script>
var respecConfig = {
   xref: "web-platform", 
}
</script>
<body data-cite="CSS  OTHER-SPECS-HERE"> 

[tabatkins]

Yeah, I knew at some point I'd need to worry about profiles, it just hadn't become a problem yet. ^_^

[marcoscaceres]

Ok cool. Anyway, as a happy Bikeshed user too, I'm happy to help as I also don't like dealing with the global namespace collisions when editing specs. If you see more collisions, please do ping me and I can help sort things out - but please please please let's not turn it into a Bikeshed vs ReSpec thing. We are doing the best we can and will continue to fix issues as quickly as possible.

[tabatkins]

Oh yeah, not intending to, apologies if you got any whiff of that here. I was just providing some context.

[marcoscaceres]

Closing in favor of w3c/aria#1510 ... nearly fixed and new goodies properly exported :D