Respec: Why do some specs end up with a class="informative" on body?
Important info
URL to affected specs:
https://w3c.github.io/beacon/
https://wicg.github.io/InputDeviceCapabilities/
https://w3c.github.io/input-events/
https://w3c.github.io/mst-content-hint/
https://w3c.github.io/server-timing/ReSpec version: 24.34.6
(Not sure whether this is a new issue. All I can say is that it wasn't the case with v23.7.1 which Reffy used until now)
Description of problem
The above specs end up with an informative class on <body>. These specs do define normative WebIDL though, so I'm expecting such a flag to appear at that level.
Typically, I understand the informative class to mean "the whole section [here the entire body] contains informative content". I typically use that flag in Reffy to skip over informative sections when crawling specs to extract WebIDL content.
Is it a bug with the specs themselves, e.g. because they don't have a <section id="conformance"> (the Beacon spec does have a conformance section but not flagged as such, the others don't)? A bug with Respec that shouldn't flag body as informative? Or is my expectation regarding the informative class wrong?
tidoust
All 8 comments
I'm not sure of the intended behavior. But I think if the spec contains normative content, they should have conformance section too.
This should help anyone looking into this issue:
Relevant code: https://github.com/w3c/respec/blob/0c9f5bd118e02aed32073dcc3123900a49e83fb1/src/core/inlines.js#L183-L186
Relevant PR: https://github.com/w3c/respec/pull/2122/ for https://github.com/w3c/respec/issues/2051
sidvishnoi
on 20 Nov 2019
Yes, this by design. Without a conformance section ReSpec can鈥檛 make a determination on what RFC2119 terms or citations mean.
marcoscaceres
on 20 Nov 2019
@tidoust, all that is needed is <section id="conformance"></section> somewhere. ReSpec will fill in the details (the Beacon spec is nearly right, but missing the id=... and shouldn't include the boilerplate text... let ReSpec fill that).
marcoscaceres
on 21 Nov 2019
OK, then the listed specs need fixing :) I'll create bugs or PR for them.
I'm all for requiring conformance sections in normative specs. From a UX perspective, it might have been clearer to be explicit about it. That is, instead of silently assuming that the content is informative when the conformance section is missing, ReSpec could actually report an error such as "No conformance section found for this normative specification. If the spec is meant to be informative-only, please add an informative class to <body> (or set noRecTrack)" or something like that.
Granted, that would require an update of existing non-normative documents, but silently switching the spec to informative triggers side effects on references that authors may not necessarily notice or understand. Typically, ReSpec reports "Normative references in informative sections are not allowed" warnings for most of the specs I listed. But then the author never flagged sections as informative, so the warning is a bit confusing. For Input Events, there's not even a warning: all references are simply thought to be informative and this seems to have gone unnoticed when the spec was last published to /TR/.
Something for the backlog perhaps. In the meantime, I propose to update the examples in the wiki as well to point out that the conformance section is mandatory for specs with normative content. Happy to take care of it.
tidoust
on 21 Nov 2019
Yeah, really good suggestions.
marcoscaceres
on 21 Nov 2019
Ok, added this to the list of enhancements to make. PR welcome, otherwise we will try to get to it as soon as we can.
marcoscaceres
on 21 Nov 2019
@ridhishjain would you like to work on this?
sidvishnoi
on 11 Dec 2019
Absolutely @sidvishnoi
Sorry for delay, was busy with another issue
ridhishjain
on 14 Dec 2019
Related issues
noamr
路
3Comments
saschanaz
路
3Comments
saschanaz
路
6Comments
deniak
路
5Comments
marcoscaceres
路
6Comments
Most helpful comment
OK, then the listed specs need fixing :) I'll create bugs or PR for them.
I'm all for requiring conformance sections in normative specs. From a UX perspective, it might have been clearer to be explicit about it. That is, instead of silently assuming that the content is informative when the conformance section is missing, ReSpec could actually report an error such as "No conformance section found for this normative specification. If the spec is meant to be informative-only, please add an
informativeclass to<body>(or setnoRecTrack)" or something like that.Granted, that would require an update of existing non-normative documents, but silently switching the spec to informative triggers side effects on references that authors may not necessarily notice or understand. Typically, ReSpec reports "Normative references in informative sections are not allowed" warnings for most of the specs I listed. But then the author never flagged sections as informative, so the warning is a bit confusing. For Input Events, there's not even a warning: all references are simply thought to be informative and this seems to have gone unnoticed when the spec was last published to /TR/.
Something for the backlog perhaps. In the meantime, I propose to update the examples in the wiki as well to point out that the conformance section is mandatory for specs with normative content. Happy to take care of it.