Re: [PATCH] introduction: Clarify RFC 2119 key words usage

["Michael S. Tsirkin" <mst@redhat.com>]

On Fri, Jun 27, 2025 at 07:19:54AM +0300, Parav Pandit wrote:
> 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 <parav@nvidia.com>
> ---
>  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}


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.

> -- 
> 2.34.1