search

speced / bikeshed

:bike: A preprocessor for anyone writing specifications that converts source files into actual specs.
https://speced.github.io/bikeshed
Creative Commons Zero v1.0 Universal
1.12k stars 200 forks source link

Auto-generated "Conformance" section looks a bit weird #2942

Open leo-barnes opened 1 month ago

leo-barnes commented 1 month ago

See this issue for reference: https://github.com/AOMediaCodec/av1-avif/issues/282

The generated Conformance section looks like this:

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Why do we have the extra RFC2119 mentioned right at the end as an extra link? Why not simply make the first two mentions of RFC2119 regular spec links?

wantehchang commented 1 month ago

Another minor issue is the example of an informative note:

Note, this is an informative note.

It is more common to follow "Note" or "NOTE" with a semicolon (:) than a comma (,).