Editorial: Revise reference links with bikeshed

[monica-ch]

This is the continuation of PR #1760 to fix reference links with dfn's.

This PR revise the links for HTML and RFC2397.

---

Preview | Diff

[yoshisatoyanagisawa]

Thanks for working on this.
I understand you prefer to set shorter-names, but I am afraid of the name conflicts.

[mkruisselbrink]

I would strongly discourage adding references to other specs in the "anchors" block like this. If there are definitions in other specs that you need to reference they should be exported from the other spec, rather than worked around like this (and I think even if they aren't exported, you can still link to them without adding them to anchors by explicitly mentioning the spec).

And the same probably also applies to all the existing html fetch and storage references below.

[yoshisatoyanagisawa]

There are actually four ways to create a link to other specification:

1. W3C standard exports, and use it directly [=something=], which might be what you recommend.
2. the "anchors" block to explain the combination of spec and text to be linked. Then, use it in the .bs file.
3. [=something=](https://example.com) style link to directly add a link.
4. <a href="https://example.com">something</a> to directly add a link.

How do you use them differently? Or, are there a style guide or so to explain the recommended way? In #1760 (comment), I suggested to modify 3 and 4 to either of 1 or 2. I am quite sure that brought this change.

[mkruisselbrink]

As https://speced.github.io/bikeshed/#custom-dfns sort of hints at, the "anchors" block exists to link to specs that are not in the autolinking database. If a spec is in the autolinking database (as w3c specs all should be) you should never need to use it. You can use an explicit <l spec='html'> indication to link to unexported definitions (although you should probably still work with the target spec to make sure the definition does get exported). Maybe link-defaults also work to explicitly link to an unexported definition. But in either case using anchors to link to specs means for one that you won't get any bikeshed warnings if the destination doesn't exist (or stops to exist), and in general just makes the spec way less maintainable.

[monica-ch]

I created #1763 to track this work. Thanks for bringing this.

[yoshisatoyanagisawa]

Thanks for the reply and sorry for the delay, let me dump what I understood:

1. use the W3C spec exported dfns (i.e. autolinking database) as much as possible. It allows bikeshed to find out the broken links when it happens.
2. if it is not possible (e.g. not W3C spec or so), the "anchors" block or the explicit indication can be used as a fallback, but makes maintainability bad because of bikeshed does not find the broken link.

Let me discuss the next actions in the #1763.