Open domenic opened 7 months ago
I've seen a lot of people just go straight for that last option
Are you seeing this in published specs in the wild, or is it something you tend to catch during review?
Either way: SGTM. And I appreciate the "using synonyms" guidance in the proposed documentation.
Are you seeing this in published specs in the wild, or is it something you tend to catch during review?
It's something I tend to catch during review, but it looks like a few have slipped through:
This looks good to me, I'm happy to have the workaround be pushed further into the docs rather than presented in the error message. PR welcome!
Currently if you use a disallowed RFC 2119 keyword in a non-normative section, you get this error:
RFC2119 keyword in non-normative section (use: might, can, has to, or override with <span class=allow-2119>):
I've seen a lot of people just go straight for that last option, not seeming to understand that this rule is there for a good reason, and that exceptions are meant to be very rare.
My best suggestion is that "we" (me, probably?) puts together some documentation about this somewhere, and then we expand the error message to link to it. And maybe even we remove the quick-fix from the error message? So it becomes something like:
RFC2119 normative keyword in non-normative section. Use a synonym, or learn more at https://speced.github.io/bikeshed/#accidental-2119, including workarounds for exceptional cases.
And here's a draft of what that documentation could look like:
Thoughts or refinements? I can try to work on a PR implementing the above if you agree.