[PATCH] introduction: Clarify RFC 2119 key words usage
Parav Pandit <[email protected]>
| Newsgroups | dev.linux.lists.virtio-comment |
|---|---|
| Message-ID | <[email protected]> |
RFC 2119 key words should be used in Requirements and Conformance sections; these key words to be avoided in rest of the sections. The motivations for such clarity are: 1. To clarify the intent: These key words carry precise semantic weight. When a spec says MUST, it means compliance is not optional. Using such terms in general or explanatory text risks misinterpreting guidance as a requirement. 2. Avoiding Ambiguity: If normative language is used in non-normative (informative) sections, it becomes unclear whether the reader is required to follow it or if it's just background or suggestion. 3. Informative sections explain context, rationale, or examples. Normative sections define rules. Mixing the two muddies the structure and weakens the authority of the normative part. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/230 Signed-off-by: Parav Pandit <[email protected]> --- introduction.tex | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/introduction.tex b/introduction.tex index 80aa67a..4e7ab59 100644 --- a/introduction.tex +++ b/introduction.tex @@ -196,7 +196,10 @@ \section{Terminology}\label{Terminology} ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``NOT RECOMMENDED'', ``MAY'', and ``OPTIONAL'' in this document are to be interpreted as described in \hyperref[intro:rfc2119]{[RFC2119]} and \hyperref[intro:rfc8174]{[RFC8174]} when, -and only when, they appear in all capitals, as shown here. +and only when, they appear in all capitals, as shown here. The use of these +key words is recommended in the Requirements and Conformance sections and should +be avoided in other sections. + \subsection{Legacy Interface: Terminology}\label{intro:Legacy Interface: Terminology} -- 2.34.1