w3c / w3c/mathml

review MUST/MAY/SHOULD

Open
#582 1 comment 0 reactions 1 assignee View on GitHub

@davidcarlisle is already working on this.

Since Jun 26, 2026.

MathML 4 need specification update
Dominant language
HTML
Stars
82
Forks
23
PR merge metrics
No merged PRs in 30d

Description

Coming up from WG discussions elsewhere, a tracking issue for MUST/MAY/SHOULD usage.

Appendix D says

The key words MAY, MUST, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Currently these RFC forms are almost exclusively used in Chapter 7 and Appendx D.

Word Occurrences Location
may 324
MAY 7 3 in Chap5, 3 in Chap7, 1 in AppD
must 77
MUST 5 4 in Chap7, 1 in AppD
should 429
SHOULD 17 1 in Chap2, 2 in Chap5, 1 in Chap6, 11 in Chap7, 2 in AppD

RFC 2119 which defines these terms says

6. Guidance in the use of these Imperatives

Imperatives of the type defined in this memo must be used with care and sparingly.
In particular, they MUST only be used where it is actually required for interoperation
or to limit behavior which has potential for causing harm...

My own view is that upper-casing these terms in the main part of the document disturbs normal reading and doesn't add anything as the style of the MathML spec is not as a sequence of testable assertions where these references are most useful.

Plan A

My preferred action would therefore be to lower-case the existing 7 instances that occur before Chapter 7.

There was some pushback on this during a recent WG call so this issue is being opened to develop a proposal for

Plan B

Review the usage on a per chapter basis and recommend introducing more upper case usage, either here or via PR, to be determined.
I haven't started that yet, but opening this issue as a place holder.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.