data-apis
Making RFC 2119 usage clearer
I've
- Added text to the end of the term definitions indicating that RFC 2119 is used.
- Add a Sphinx extension that automatically bolds RFC 2119 words.
However, note that our usage of some of the RFC terms is not always consistent, especially for less used terms like "required", "may", "optional", and "recommended". So I would suggest that we either
- Audit our use of these terms and fix them to align with RFC 2119 usage.
- Add some text to clarify that certain terms are not used in accordance with RFC 2119.
For example, we use the term "optional" to refer to "optional parameters".
Fixes https://github.com/data-apis/array-api/issues/796
Thanks, @asmeurer, for opening the draft PR. If we are going to try to auto-bold, this should only apply to the documents under "API Specification" and "Extensions". Much of the other content is narrative text and should not fall under RFC 2119.
Also, swapping out the rst table for a list table seems unrelated to the changes described in the OP. That may be better left to a small separate PR to keep things clean.
One last addendum: the only words we apply from RFC 2119 are must and should. I don't believe we have a written record of this, but those were the only two words which we sought to apply when originally considering RFC 2119 for use in the specification.
Also, swapping out the rst table for a list table seems unrelated to the changes described in the OP. That may be better left to a small separate PR to keep things clean.
There was a build error related to this table. I think adding the bold messed up the formatting of the table.
We should consider that if we say that we follow RFC 2119, then it would be better to follow it consistently, meaning in all documents, and also follow it completely, meaning the full set of words. If we don't do this, then we need to make it very clear that we aren't, but it would be clearer to people familiar with the RFC conventions if we did.
We should consider that if we say that we follow RFC 2119, then it would be better to follow it consistently, meaning in all documents, and also follow it completely, meaning the full set of words. If we don't do this, then we need to make it very clear that we aren't, but it would be clearer to people familiar with the RFC conventions if we did.
We'll need to update quite a bit of copy then, as a fair amount of copy when discussing, e.g., the test suite or methodology or various design topics is not actually normative.
I think, as a first pass, if we can limit to only the specification directories ("API Specification" and "Extensions"), that would be preferable. Otherwise, the non-normative content becomes confusing in its own right.