introduction: Clarify RFC 2119 key words usage
PATCH 1/1 introduction: Clarify RFC 2119 key words usage
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.
--- introduction.tex | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
introduction.tex +4 -1
@@ -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}
Signature · 1 line
2.34.1
Quoted 19 lines · Parav Pandit
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.
Quoted 5 lines
Signed-off-by Parav Pandit <[email protected]>--- introduction.tex | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
Quoted 19 lines · Parav Pandit
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.
Quoted 5 lines
Signed-off-by Parav Pandit <[email protected]>--- introduction.tex | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
Quoted 30 lines · Parav Pandit
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.
Signed-off-by Parav Pandit <[email protected]>--- introduction.tex | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)introduction.tex +0
-0
introduction.tex \section{Terminology}\label{Terminology} · line 204
Quoted 10 lines
introduction.tex +4
-1@@ -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}
The spec is for the reader, who has nothing to gain from this and will just be confused. If you want to start a document with suggestions for contributors, that might be a great idea, and this might belong there.
Quoted 2 lines
Signature · 1 line
2.34.1
Quoted 40 lines
From: Michael S. Tsirkin <[email protected]>
Sent: 27 June 2025 05:23 PMQuoted 31 lines · Parav Pandit
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.
Signed-off-by Parav Pandit <[email protected]>--- introduction.tex | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)introduction.tex index renamed from introduction.tex +0
-080aa67a..4e7ab59 100644
introduction.tex +0
-0@@ -196,7 +196,10 @@ \section{Terminology}\label{Terminology} ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``NOT RECOMMENDED'',Quoted 3 lines
``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.
Quoted 14 lines
introduction.tex \section{Terminology}\label{Terminology} · line 204
Quoted 6 lines
introduction.tex +4
-0+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}The spec is for the reader, who has nothing to gain from this and will just be confused. If you want to start a document with suggestions for contributors, that might be a great idea, and this might belong there.
Quoted 2 lines
--
2.34.1
Yeah, that contributor's doc is a good idea.
We already have one.
I will just extend https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md