Do we have a style for when to add [SPECNAME] to the end of a paragraph?

[domenic]

Continuing discussion from whatwg/infra#156 (comment)

At one extreme, every time we reference a concept or algorithm from another specification, the end of that paragraph should contain a [SPECNAME] reference. I think that's what @annevk is claiming has been the style.

If so, we're not at all consistent about it, especially within algorithm steps. A bunch of places call algorithms or use concepts from other specs without adding a [specname] at the end of the line. E.g. https://xhr.spec.whatwg.org/#dom-xmlhttprequest-send step 4, or https://html.spec.whatwg.org/multipage/webappapis.html#runtime-script-errors step 5, or everywhere that throws a TypeError without referencing ES.

At the other extreme these [SPECNAME] things should not generally be used unless you are mentioning the spec by name. E.g. https://html.spec.whatwg.org/multipage/webappapis.html#integration-with-the-javascript-module-system intro paragraph. The reference is implicit if you are cross-linking correctly.

The latter seems to be what we do more often, in my experience.

[annevk]

What I typically do is to have a Terminology/Infrastructure section that lists a bunch of specifications I used terminology from, e.g., https://fetch.spec.whatwg.org/#infrastructure. And then for one-off cases I add [SPECNAME] after the affected paragraph. The latter seemed more relevant here, at least for now.

I'm not a big fan of [SPECNAME] in general though. It really seems like an artifact from a time before hyperlinks. Having said that, in my experience people do appreciate:

1. Having an upfront declaration where terminology might be used from.
2. A references section that states normative dependencies.

But I never really drilled down into what those sections end up conveying to various folks and how we could approach that better.

[Ms2ger]

Possibly it might be useful to have an auto-generated index of terms that are depended on.

[tabatkins]

Now that spec cross-linking is so prevalent and easy, and the index and bibliography automatically mention the spec when you link to it, I don't think it's ever really necessary to add [SPEC] explicitly except when you're purposely mentioning and linking to the spec itself in your prose.

This is the style fantasai and I have slipped into in our own editing.

[annevk]

[SPEC] in https://xhr.spec.whatwg.org/#index-defined-elsewhere does not link to the references section though. Should it? Also, how would that end up knowing whether it's normative or non-normative?

[tabatkins]

[SPEC] in xhr.spec.whatwg.org/#index-defined-elsewhere does not link to the references section though. Should it?

I could probably do that.

Also, how would that end up knowing whether it's normative or non-normative?

Biblio autolinks link up to the index correctly whether the biblio entry shows up in normative or informative. (If a biblio is referenced as both, it only shows up in the normative section.) So nothing special has to be done here; the autolink will just be encoded as an informative ref and everything'll work out fine.

[annevk]

I think there's one other case where [SPEC] is warranted, which is in examples and explanatory notes. They might mention some other technology to illustrate a point and to aid the reader it would help if there was a (non-normative) reference that explains that technology.

So maybe the rule is that for normative usage it should always go through direct links to concepts and algorithms. But non-normative usage can do with a hand-wavy [SPEC] at the end of the paragraph.