speced / bikeshed

:bike: A preprocessor for anyone writing specifications that converts source files into actual specs.

Home Page:https://speced.github.io/bikeshed

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Unable to reference algorithm exported by another specification

jugglinmike opened this issue · comments

Given input like

1. For each |session| in the [=set of sessions for which an event is enabled=]:

bikeshed spec reports the following error:

LINE ~4995: No 'dfn' refs found for 'set of sessions for which an event is enabled' that are marked for export.
[=set of sessions for which an event is enabled=]

The term is defined in the WebDriver BiDi proposal, and BikeShed's ref database has two entries for it:

$ bikeshed refs --spec webdriver-bidi | grep 'set of sessions' -A9
text:      set of sessions for which an event is enabled
type:      dfn
spec:      webdriver-bidi
shortname: webdriver-bidi
level:     
status:    anchor-block
url:       https://w3c.github.io/webdriver-bidi/#set-of-sessions-for-which-an-event-is-enabled
export:    True
normative: True
for_:      []
--
text:      set of sessions for which an event is enabled
type:      dfn
spec:      webdriver-bidi
shortname: webdriver-bidi
level:     1
status:    current
url:       https://w3c.github.io/webdriver-bidi/#set-of-sessions-for-which-an-event-is-enabled
export:    False
normative: True
for_:      []

The first entry listed there is from your own anchor block. The second is from the actual spec, tho, and is marked as unexported.

The ideal fix is to ask webdriver to export the definition. In the meantime, you can override Bikeshed's automatic ignoring of unexported definitions by specifying that you do indeed want the definition from that spec - either use a link-defaults like:

<pre class=link-defaults>
type: dfn; spec: webdriver-bidi; text: set of sessions for which an event is enabled;
</pre>

or just annotate it at the callsite. The easiest way is to use the <l> wrapper that just wraps autolinks and can hold attributes for them, like:

1. For each |session| in the <l spec=webdriver-bidi>[=set of sessions for which an event is enabled=]</l>:

The fact that your anchor block isn't linking is curious, tho. I wonder if it's something to do with it not having a level?

My anchor block is indeed linking as expected--it's just that I wrote up this report after I'd already implemented the workaround. (I didn't recognize that bikeshed refs also takes the local document into consideration; I figured the repeated entries were indicative of some publication error.) Thanks for the support!

Ah, phew, tho please note that anchor blocks are intrinsically fragile - they bypass the entire autolinking system and will bitrot if anything ever moves. Using a link-defaults is vastly preferred for things like this.