Respec: Add xref examples

[saschanaz]

Just tried to do the following in examples/basic.built.html:

[Constructor]
interface Foo {
  attribute DOMString bar;
  void doTheFoo(optional EventInit init);
};

But xref doesn't automatically link EventInit. What should be done exactly? We should add an xref example and possibly some short guide on example documents. @sidvishnoi @marcoscaceres

[sidvishnoi]

xref doesn't automatically link EventInit. What should be done exactly?

EventInit is defined in DOM only. Whereas, the xref by default doesn't search in DOM. Adding a data-cite="dom" to any parent of this IDL block will fix it.
Another way would be to add respecConfig.xref = "web-platform" (which I think should've been the default case)

Examples and short guide are in todo list. On the higher priority, we need to improve the xref error messages and provide useful hints when linking fails.
We can do a second run of xref api search for finding the useful hints for the failed links.

[sidvishnoi]

@marcoscaceres Why are we not using "web-platform" by default? Or is it a bug?
https://github.com/w3c/respec/blob/f4774be2dadc204e69c768232ba9ca1a2d7d8053/src/core/xref.js#L69-L81

[marcoscaceres]

not a bug... want Editors to think about which specs they are actually citing. Using "web-platform" is nice, but "with great power comes great responsibility" 🕷

[saschanaz]

Letting editors think is good, but failing by default without a quick guide to fix is bad. Maybe we should at least change the link error message...

[marcoscaceres]

yes, agree. Definitely need good examples too.

[sidvishnoi]

For a quick one, when we have a date-cite (from some parent or self), we can change the error message to "couldn't find term X in either of these specs: spec1, spec2,.."

[saschanaz]

I think we should at least include webidl for the default value of xref, otherwise even DOMString and [Constructor] fail to link and throw. WDYT? @marcoscaceres

[sidvishnoi]

That reminds me of an incomplete item in initial xref checklist https://github.com/w3c/respec/issues/1662#checklist

Automatically add data-cite="webidl" to nearest <section> if it has pre.idl

[marcoscaceres]

Added more details to https://github.com/w3c/respec/wiki/xref#xref