Cross-spec links are broken

[markafoltz]

It looks like the recent inclusion of the Presentation API and Remote Playback API in "shepherd" has broken the section autolinking for this spec. Even if I update an autolink to match the section ID exactly, Bikeshed complains that it can't find them.

See e.g. the results of trying to merge #302:

https://github.com/w3c/openscreenprotocol/actions/runs/3162168763/jobs/5148517856

I think some of the autolinks are to terms that are not exported by the specs (and thus need to be defined inline) but it would be helpful to know how to fix the autolinks that should work, first.

Any ideas @tidoust ?

[tidoust]

It looks like the recent inclusion of the Presentation API and Remote Playback API in "shepherd" has broken the section autolinking for this spec. Even if I update an autolink to match the section ID exactly, Bikeshed complains that it can't find them.

Ah. It seems Shepherd cannot extract headings in specs generated with ReSpec. I don't know what Shepherd expects. I asked in https://github.com/tabatkins/bikeshed/issues/1664#issuecomment-1264307993. Bikeshed assumes that the references are invalid as a result. I don't know how to work around this problem in the meantime without hardcoding the links with <a href="...">... which would defeat the point of adding the specs to the cross-references database in the first place.

I think some of the autolinks are to terms that are not exported by the specs (and thus need to be defined inline) but it would be helpful to know how to fix the autolinks that should work, first.

Yes, these are normal. We could flag these definitions as "exported" in the Presentation API and Remote Playback API to avoid defining terms inline in the Open Screen Protocol (and to avoid running in situations where the Open Screen Protocol references terms that no longer exist in the Presentation API and Remote Playback API).

[markafoltz]

I updated my local copy of bikeshed and now the section/header API cross-references are all successfully linking 👏

There is a new list of complaints about missing xrefs for attributes and methods HTMLMediaElement. I think it's just the wrong syntax.

I will see if I can get all the fixes into #302 and then merge that.

[markafoltz]

Now blocked on an inability to resolve IDL references for {{HTMLMediaElement}}. Unsure what the root cause is as this syntax seems to work in other bikeshed specs (and they don't specify HTML as the source of the xref).

Hmm.

bikeshed --print=plain spec index.bs
LINK ERROR: No 'idl' refs found for 'HTMLMediaElement'.
{{HTMLMediaElement}}
LINK ERROR: No 'element-sub' refs found for 'src'.
<{source/src|source URL}>
LINK ERROR: No 'element-sub' refs found for 'type'.
<{source/type|extended MIME type}>
LINK ERROR: No 'idl' refs found for 'fastSeek()'.
{{HTMLMediaElement/fastSeek()|HTMLMediaElement.fastSeek()}}
<snip>

[markafoltz]

@tidoust

Unfortunately this seems to have regressed:

https://github.com/w3c/openscreenprotocol/actions/runs/3363338321/jobs/5576337767

  [INFO] Build bikeshed document "index.bs" (gh)…
    $ bikeshed --die-on=fatal spec "index.bs" "index.bs.built.html" 
      LINE ~782: Couldn't find section '#creating-a-receiving-browsing-context' in spec 'presentation-api-1':
      [[PRESENTATION-API#creating-a-receiving-browsing-context|section 6.6.1]]
       ✘  Did not generate, due to fatal errors
    Command `bikeshed --die-on=fatal spec "index.bs" "index.bs.built.html" ` failed with exit code: 2.

I thought it was a problem with my local install, so I tried upgrading bikeshed and the anchors database locally. However our GitHub action encounters the same issue.

[markafoltz]

Probably related to https://github.com/tabatkins/bikeshed/issues/2379 😕

[tidoust]

Probably related to tabatkins/bikeshed#2379 😕

That was the cause. Bug has now been fixed and Bikeshed generation no longer chokes on missing headings.