tabatkins
Deep linking bibliographic references not working
I find that something like [[!RFC9110#name-origin-server]] is not working.
And when I try to compile a spec with [[RFC9110#name-origin-server]], I get an error:
Couldn't find section '#name-origin-server' in spec 'rfc9110':
[[RFC9110#name-origin-server]]
This seems contrary to the language of https://speced.github.io/bikeshed/#autolink-biblio?
Right now, you need to use [[!RFC9110#section-3.6]] to reference section 3.6 Origin Server in RFC9110.
This is a consequence of the way headings get extracted to populate Webref, the cross-reference database that Bikeshed makes use of. When there is an ID attached to a heading element (e.g. <h2>) and an ID on the wrapping <section>, the crawler extracts the ID of the wrapping <section>. This results in "better" IDs for most specifications, except for more recent RFCs published under www.rfc-editor.org, where the IDs that appear on the wrapping <section> are less human-friendly.
We may end up changing the logic for these RFCs, but some specs use the section IDs already. They would need to be updated as we make the change.
More importantly, for RFC9110, note that we're actually rather considering using the httpwg.org version of the RFC because it is more readable than - and as "canonical" as - the www.rfc-editor.org version. Such a change would also break building of specs that reference RFC9110 sections. Reference would become [[!RFC9110#origin.server]] with that change (unfortunately, the www.rfc-editor.org and the httpwg.org versions do not use the same fragment IDs).
We could also perhaps extract both fragment IDs but tools such as Bikeshed and ReSpec would then need to be adjusted to know where to look for these additional IDs.
(Side note that it would probably be useful for spec authors to have a lookup mechanism for headings at hand, similar to the one exposed by ReSpec for dfns).
@tidoust Thank you for a detailed answer. I could work with section numbering for now!
Consider adding this to the docs (so that other don't waste time researching and experimenting with the same issue as I did)!
Re httpwg.org version: I prefer that for my own reference and it has simpler ids. And RFC911x are special. But I can also see the merits in linking to the place that is supposed to keep all RFCs.
Lastly, I tried the ReSpec search, I guess it is exclusive to dfns and not headings.
Re httpwg.org version: I prefer that for my own reference and it has simpler ids. And RFC911x are special. But I can also see the merits in linking to the place that is supposed to keep all RFCs.
The data is still propagating as I write this message (the latest data has not yet reached the online Bikeshed service at least), but the httpwg.org version is now used in Webref for all RFCs that have one.
The direct consequence is that [[RFC9110#section-3.6]] will no longer work. That reference will need to be replaced by [[RFC9110#origin.server]] to generate https://httpwg.org/specs/rfc9110.html#origin.server
I prepared pull requests against specs that I'm aware of (essentially those that are in the cross-references database) and that link to sections in RFC911x specs. If there are Bikshed specs that are not in browser-specs and that also contain such links, they will also need to be updated!