Respec: Reference errors flagged by respec

[dontcallmedom]

Important info

• URL to affected spec: https://w3c.github.io/webrtc-pc/webrtc.html
• ReSpec version: 24.30.5
• [x] I did a "hard refresh", but it's still busted.

Description of problem

What happened (e.g., it crashed)?:
When trying to upgrade the WebRTC spec above (whose online version is currently tied to a static version of ReSpec 24.3.0), it triggers 30 new errors bound to interfaces or names it does not recognize, even though these names are indeed defined in normatively referenced specifications.

For instance, it complains:

Couldn't match "EventTarget" to anything in the document or in any other document cited in this specification: bundle, ice, jsep, sdp, sdp-simulcast, trickle-ice, webidl. See how to cite to resolve the error at: 1.

I'm not sure why it picks that random subset of references; we do normatively reference DOM where EventTarget is defined. Similar error messages get generated for a bunch of other interfaces.

More bizarrely, a similar error message is generated for "Constructor":

Couldn't match "Constructor" to anything in the document or in any other document cited in this specification: bundle, ice, jsep, sdp, sdp-simulcast, trickle-ice, webidl. See how to cite to resolve the error

The How-to-cite links don't really help; I noticed that some well-known names (e.g. VoidFunction) don't appear in the auto-complete box there though.

But what I was expecting?:
No errors for interfaces that are normatively referenced; no error for using the Constructor extended attribute.

[marcoscaceres]

I'm not sure why it picks that random subset of references; we do normatively reference DOM where EventTarget is defined. Similar error messages get generated for a bunch of other interfaces.

References are contextual (i.e., it looks in the DOM tree)... so, to fix, in theory, you need to add data-cite="DOM" where the <pre class="IDL"> is defined.

More bizarrely, a similar error message is generated for "Constructor":

As of like 3 days ago, Constructor is no longer a thing in WebIDL so it's getting confused. We are working to add support for constructor() right now :)

Will jump over to the WebRTC pull request and give you a hand soon!

[dontcallmedom]

ah, thanks for the data-cite trick, that helps solve most of the reference issues.

Besides the Constructor error, respec still doesn't recognize the following names:

• AlgorithmIdentifier defined in Web Crytpo
• VoidFunction defined in WebIDL

Neither of those appear in the autocompletion box in https://respec.org/xref/

[marcoscaceres]

Great! will need to check why they are not being exported to Shepherd.

[gkellogg]

I am seeing numerous cross-reference errors in my specs as of today:

• https://w3c.github.io/json-ld-syntax/
• https://w3c.github.io/json-ld-api/
• https://w3c.github.io/json-ld-framing/

Running ReSpec 24.31.0. These were all stable as of last week. The errors seem to be reported where a plural reference is used to a singular definition. For example, 'Couldn't match "iris" to anything in the document ', but https://w3c.github.io/json-ld-api/#dfn-iri is defined, and is a data-cite to https://tools.ietf.org/html/rfc3987#section-1.3 (it should be a direct reference, rather than going through the local dfn with data-cite). Something seems to have broken with automatic pluralization.

[marcoscaceres]

Fix for plurals failures coming soon https://github.com/w3c/respec/pull/2505

[dontcallmedom]

should I raise the problem with VoidFunction and AlgorithmIdentifier as a separate issue since that one got closed?

[marcoscaceres]

It seems neither of those have been exported to Shepherd.

[marcoscaceres]

WebCrypto is too old I think to be part of Shepherd, so we will need to link to it using the old method: data-cite="foo#bar”. I’m afk, but will check why VoidFunction is lacking data-export.

[sidvishnoi]

Found respec-xref-route doesn't have callback in supported IDL types
(https://respec.org/xref/meta/types). VoidFunction has callback type. Sending PR..

PR: https://github.com/sidvishnoi/respec-xref-route/pull/52

[dontcallmedom]

@marcoscaceres if you can say a bit more about the old method - I don't know how to apply it effectively to an IDL fragment.

[sidvishnoi]

@dontcallmedom add the following somewhere in the document and the IDL block will link it correctly (workaround).

<dfn data-cite="WebCryptoAPI/#dfn-AlgorithmIdentifier">AlgorithmIdentifier</dfn>

@marcoscaceres should we add a config option to define the terms that can't be added to xref database? Something like localBiblio? It may not be always meaningful to add a dfn in markup just for xref linking.

[dontcallmedom]

thanks @sidvishnoi that works!

[sidvishnoi]

@dontcallmedom VoidFunction should also work now by default. Thanks for letting us know.

[marcoscaceres]

@gkellogg, most errors relating to plurals should be fixed. Will check first thing tomorrow what's going on with those last few errors. Thanks for your patience and apologies for the recent breakage... something about "breaking eggs to make omelettes" :)

[gkellogg]

@gkellogg, most errors relating to plurals should be fixed. Will check first thing tomorrow what's going on with those last few errors. Thanks for your patience and apologies for the recent breakage... something about "breaking eggs to make omelettes" :)

The final errors are all related to references into WebIDL defined entries such as <a data-link-for="JsonLdOptions">ordered</a> which is defined in the JsonLdOptions section as <dfn data-dfn-for="JsonLdOptions">ordered</dfn>.

[marcoscaceres]

closing, as I think all issues have been addressed.

@marcoscaceres should we add a config option to define the terms that can't be added to xref database? Something like localBiblio? It may not be always meaningful to add a dfn in markup just for xref linking.

I'm not sure... I still think defining terms directly in the spec fine. You would either have to do it in something like localBiblio or directly in markup via a dfn. Generally, we always use HTML over JS for these things.